Improve readme

Improve readme

Author: Mic92

README.md

@@ -1,30 +1,78 @@
 # Buildbot-nix
 
-A nixos module to make [buildbot](https://www.buildbot.net/) a proper Nix-CI.
+Buildbot-nix is a NixOS module designed to integrate
+[Buildbot](https://www.buildbot.net/), a continuous integration (CI) framework,
+into the Nix ecosystem. This module is under active development, and while it's
+generally stable and widely used, please be aware that some APIs may change over
+time.
 
-For an example checkout the [example](./examples/default.nix) and the module
-descriptions for [master](./nix/master.nix) and [worker](./nix/worker.nix).
+## Getting Started with Buildbot Setup
 
-This project is still in early stage and many APIs might change over time.
+To set up Buildbot using Buildbot-nix, you can start by exploring the provided
+examples:
 
-## Github
+- Check out the basic setup in [example](./examples/default.nix).
+- Learn about configuring the Buildbot master in
+  [master module](./nix/master.nix).
+- Understand how to set up a Buildbot worker in
+  [worker module](./nix/worker.nix).
 
-We currently primarly support Github as a platform but we are also looking into
-supporting other CIs such as gitea.
+Additionally, you can find real-world examples at the end of this document.
 
-Buildbot requires a GitHub app, to allow login for GitHub users to its
-dashboard. After installing the app, create oauth credentials and set them in
-the buildbot-nix nixos module.
+Buildbot masters and workers can be deployed either on the same machine or on
+separate machines. To support multiple architectures, configure them as
+[nix remote builders](https://nixos.org/manual/nix/stable/advanced-topics/distributed-builds).
+For a practical NixOS example, see
+[this remote builder configuration](https://github.com/Mic92/dotfiles/blob/main/nixos/eve/modules/remote-builder.nix).
 
-Furthermore buildbot requires a github token with the following permissions:
+## Using Buildbot in Your Project
 
-- `admin:repo_hook`, `repo`
+Buildbot-nix automatically triggers builds for your project under these
+conditions:
 
-For github organisations it's recommend to create an additional GitHub user for
-that.
+- When a pull request is opened.
+- When a commit is pushed to the default git branch.
 
-## Real-worlds deployments
+It does this by evaluating the `.#checks` attribute of your project's flake in
+parallel. Each attribute found results in a separate build step. You can test
+these builds locally using `nix flake check -L` or
+[nix-fast-build](https://github.com/Mic92/nix-fast-build).
 
-- [Nix-community infra](https://github.com/nix-community/infra/tree/master/modules/nixos)
-- [Mic92's dotfiles](https://github.com/Mic92/dotfiles/blob/main/nixos/eve/modules/buildbot.nix)
-- [Technical University Munich](https://github.com/TUM-DSE/doctor-cluster-config/tree/master/modules/buildbot)
+If you need to build other parts of your flake, such as packages or NixOS
+machines, you should re-export these into the `.#checks` output. Here are two
+examples to guide you:
+
+- Using
+  [flake-parts](https://github.com/Mic92/dotfiles/blob/10890601a02f843b49fe686d7bc19cb66a04e3d7/flake.nix#L139).
+- A
+  [plain flake example](https://github.com/nix-community/nixos-images/blob/56b52791312edeade1e6bd853ce56c778f363d50/flake.nix#L53).
+
+### Integration with GitHub
+
+Buildbot-nix primarily supports GitHub, with plans to extend support to other
+platforms like Gitea.
+
+To integrate with GitHub:
+
+1. **GitHub App**: Set up a GitHub app for Buildbot to enable GitHub user
+   authentication on the Buildbot dashboard.
+2. **OAuth Credentials**: After installing the app, generate OAuth credentials
+   and configure them in the buildbot-nix NixOS module.
+3. **GitHub Token**: Obtain a GitHub token with `admin:repo_hook` and `repo`
+   permissions. For GitHub organizations, it's advisable to create a separate
+   GitHub user for managing repository webhooks.
+
+### Real-World Deployments
+
+See Buildbot-nix in action in these deployments:
+
+- **Nix-community infra**:
+  [Configuration](https://github.com/nix-community/infra/tree/master/modules/nixos)
+  | [Instance](https://buildbot.nix-community.org/)
+- **Mic92's dotfiles**:
+  [Configuration](https://github.com/Mic92/dotfiles/blob/main/nixos/eve/modules/buildbot.nix)
+  | [Instance](https://buildbot.thalheim.io/)
+- **Technical University Munich**:
+  [Configuration](https://github.com/TUM-DSE/doctor-cluster-config/tree/master/modules/buildbot)
+  | [Instance](https://buildbot.dse.in.tum.de/)
+- **Numtide**: [Instance](https://buildbot.numtide.com)

examples/default.nix

@@ -35,6 +35,10 @@ in
             oauthId = "aaaaaaaaaaaaaaaaaaaa";
             user = "mic92-buildbot";
             admins = [ "Mic92" ];
+            # All github projects with this topic will be added to buildbot.
+            # One can trigger a project scan by visiting the Builds -> Builders page and looking for the "reload-github-project" builder.
+            # This builder has a "Update Github Projects" button that everyone in the github organization can use.
+            topic = "buildbot-mic92";
           };
           # optional expose latest store path as text file
           # outputsPath = "/var/www/buildbot/nix-outputs";