document how to build the code and contribute

README.md

@@ -1,6 +1,11 @@
-# credential-helper
+# tweag-credential-helper
 
-A credential-helper framework and agent for [Bazel](https://bazel.build/) and similar tools implementing the [credential-helper spec][spec].
+*A credential-helper framework and agent for [Bazel](https://bazel.build/) and similar tools implementing the [credential-helper spec][spec].*
+
+Many build tools need access to external resources—such as tarballs from a Git forge, container images, prebuilt artifacts, and large datasets.
+Tools like Bazel often require authentication with HTTP servers to download these files.
+This project provides a credential helper that automatically injects authentication headers based on the request URI, simplifying the process of securing your build dependencies:
+Instead of configuring credentials in your code, a credential helper decouples the authentication of requests from the configuration of external dependencies.
 
 ## Key Features
 
@@ -137,6 +142,8 @@ Alternatively, you can [write custom plugins that are part of your own Bazel wor
 
 Follow the [provider-specific documentation](/docs/providers/) to ensure you can authenticate to the service.
 
+You can also look at the [example project](/examples/full/) to see how everything works together.
+
 ## Configuration
 
 You can use environment variables to configure the helper.
@@ -171,7 +178,6 @@ Additionally, you can configure how the installer behaves by adding any of the f
   Configures the install destination of the credential helper on Windows. Subject to [prefix expansion](#prefix-expansion). Defaults to `%workspace%\tools\credential-helper.exe`, which is the path used in `.bazelrc` by default.
   Windows cannot make use of the shell wrapper, so this binary is copied to the source tree instead of a path relative to the workdir.
 
-
 ### <a name="prefix-expansion"></a> Prefix Expansion
 
 Configuration options (including envionment variables and Bazel flags) that refer to paths are subject to prefix expansion. Special prefixes listed below will be replaced by concrete paths at runtime.
@@ -203,6 +209,12 @@ Configuration options (including envionment variables and Bazel flags) that refe
     echo '{"uri": "https://example.com/foo"}' | CREDENTIAL_HELPER_LOGGING=debug tools/credential-helper get
     ```
 
+## Hacking & Contributing
+
+We invite external contributions and are eager to work together with the build systems community.
+Please refer to the [CONTRIBUTING](/docs/CONTRIBUTING.md) guide to learn more.
+If you want to check out the code and run a development version, follow the [HACKING](/docs/HACKING.md) guide to get started. 
+
 ## Security Considerations  
 
 In most circumstances, a credential helper improves security by decoupling resource configuration from the credentials required to access them. This reduces the need for hardcoded credentials stored in source code, minimizing potential security vulnerabilities.  
@@ -234,4 +246,4 @@ The agent does not implement additional countermeasures. Consequently, access to
 [spec]: https://github.com/EngFlow/credential-helper-spec
 [releases]: https://github.com/tweag/credential-helper/releases
 [go_duration]: https://pkg.go.dev/time#ParseDuration
-[plugins]: /docs/plugins.md
+[plugins]: /docs/plugins.md

docs/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to tweag-credential-helper
+
+Welcome, and thanks for considering contributing to the credential helper.
+
+## Contributing
+
+There are many useful ways to help which don't involve modifying the source code:
+
+- Improving the documentation, user-facing or internal, technical or high-level
+- Reviewing changes from other contributors
+- Creating, commenting, and voting on [discussions for new providers or features][discussions]
+
+The rest of this document is concerned with changes to the code.
+
+## Suggesting new providers, features and large changes
+
+For small fixes and improvements, it is generally acceptable to open a pull request with your change.
+If you find a bug and don't know how to best address it, create [an issue first][new-issue-bug].
+Support for new providers, features and large changes warrant the creation of a [discussion][discussions].
+This way we avoid contributors putting effort into work that is unlikely to be merged, prioritize new features and discuss how to implement complex changes.
+
+## Resources
+
+### Documentation
+
+- The [README](/README.md) contains user-facing documentationg, including setup in your own Bazel project and configuring authentication for different services.
+- The [docs](/docs) directory contains detailed documentation on each [provider](/docs/providers/), as well as a guide on developing [out-of-tree plugins][plugins].
+
+### People
+
+`tweag-credential-helper` is maintained by [Tweag][tweag]. The current project steward is Malte Poll (@malt3).
+
+You can also [join our Discord][discord-join] server and talk to us in the [credential-helper channel][discord-channel].
+
+## Setting up a development environment
+
+Please refer to [`HACKING.md`](/docs/HACKING.md) to set up a development environment, test the code on a Bazel project and run integration tests.
+
+[discussions]: https://github.com/tweag/credential-helper/discussions
+[plugins]: /docs/plugins.md
+[new-issue-bug]: https://github.com/tweag/credential-helper/issues/new?assignees=&labels=type%3A+bug&projects=&template=bug_report.md
+[discord-join]: https://discord.gg/vYDnJYBmax
+[discord-channel]: https://discord.com/channels/1174731094726295632/1326155201748668499
+[tweag]: https://www.tweag.io/

docs/HACKING.md

@@ -0,0 +1,98 @@
+# Developer Guide
+
+Most users can directly use the credential helper as a Bazel module by following the [README](/README.md).
+If you want to fix a bug or develop a new feature, follow this guide to setup your environment.
+
+## Setting up a development environment
+
+The following steps allow you to build the project and use a development version in your own Bazel module.
+
+### Install Bazel
+
+On non-NixOS systems, [Bazelisk is the recommended way of installing Bazel][install-bazelisk].
+NixOS requires a patched version of Bazel, which is available in nixpkgs (`bazel_7` is the newest version at the time of writing):
+
+```
+# Using flakes
+$ nix shell nixpkgs#bazel_7
+
+# Traditional
+$ nix-shell -p bazel_7
+```
+
+### Build the code and run unit tests
+
+To build & test everything at once:
+
+```
+$ bazel build //...
+$ bazel test //...
+```
+
+Building the helper binary directly works too:
+
+```
+# helper binary for target platform
+$ bazel build //:tweag-credential-helper
+
+# Build helper binary without Bazel (using Go)
+$ go build ./cmd/credential-helper
+
+# runnable installer target
+$ bazel run //installer
+
+# all helper binaries bundled in a release
+$ bazel build //bzl/private/release
+
+# build the full release distribution and list the contents
+$ bazel build //bzl/private/release:dist_tar
+$ tar -tvf bazel-bin/bzl/private/release/dist.tar
+```
+
+### Run integration tests
+
+The CI runs integration tests from the [examples directory](/examples) in addition to running `bazel test` on the code.
+You can do this locally as well:
+
+```
+# list all integration tests
+$ bazel query 'kind(sh_test, //examples/...)'
+
+# run all
+$ bazel test //examples:integration_tests
+```
+
+Please note that the `full` test requires real credentials for all cloud services supported by the credential helper, so expect this to fail unless you are logged in properly.
+
+### Use a development version of the credential helper
+
+Outside of Bazel, you can just [build the helper](#build-the-code-and-run-unit-tests) and invoke the binary directly:
+
+```
+echo '{"uri": "https://example.com/foo"}' | credential-helper get
+```
+
+In a Bazel project, you can use a local checkout of the `@tweag-credential-helper` module.
+Simply add the credential helper using a `bazel_dep` and then override it:
+
+`MODULE.bazel`
+
+```starlark
+module(name = "my_own_bazel_module", version = "0.0.0")
+
+bazel_dep(name = "tweag-credential-helper", version = "0.0.0")
+
+# replace path with an absolute or relative path to your local checkout
+local_path_override(
+    module_name = "tweag-credential-helper",
+    path = "/path/to/github.com/tweag/credential-helper",
+)
+```
+
+With this setup, you can then follow the regular user guide and run the installer as usual:
+
+```
+$ bazel run @tweag-credential-helper//installer
+```
+
+[install-bazelisk]: https://bazel.build/install/bazelisk