chore: rework the README (#903)

- Explain how to run tests locally instead of pointing to the
  workflow.
- Explain how to run lint checks & fix locally
- Replace the `forgejo-setup` based instructions with shorter and more
  actionable instructions based out of the end-to-end tests.
- Remove the reporting bug section, the issue template has all the
  information it needs. It is unlikely that someone reporting a bug
  will read that section in the README before filing the bug. It
  removes the suggestion to file a bug in the end-to-end repository
  but I don't think it was actually beneficial to anyone in the past
  two years.
- Remove the mock generation part as it is now self documented in the
  job that takes care of it.

<!--start release-notes-assistant-->
<!--URL:https://code.forgejo.org/forgejo/runner-->
- other
  - [PR](https://code.forgejo.org/forgejo/runner/pulls/903): <!--number 903 --><!--line 0 --><!--description Y2hvcmU6IHJld29yayB0aGUgUkVBRE1FIFtza2lwIGNhc2NhZGVd-->chore: rework the README [skip cascade]<!--description-->
<!--end release-notes-assistant-->

Reviewed-on: https://code.forgejo.org/forgejo/runner/pulls/903
Reviewed-by: Gusted <[email protected]>
Reviewed-by: Mathieu Fenniak <[email protected]>
Co-authored-by: Earl Warren <[email protected]>
Co-committed-by: Earl Warren <[email protected]>

Author: earl-warren

README.md

@@ -2,13 +2,10 @@
 
 A daemon that connects to a Forgejo instance and runs jobs for continuous integration. The [installation and usage instructions](https://forgejo.org/docs/next/admin/actions/) are part of the Forgejo documentation.
 
-# Reporting bugs
-
-When filing a bug in [the issue tracker](https://code.forgejo.org/forgejo/runner/issues), it is very helpful to propose a pull request [in the end-to-end tests](https://code.forgejo.org/forgejo/end-to-end/src/branch/main/actions) repository that adds a reproducer. It will fail the CI and unambiguously demonstrate that the problem exists. In most cases it is enough to add a workflow ([see the echo example](https://code.forgejo.org/forgejo/end-to-end/src/branch/main/actions/example-echo)). For more complicated cases it is also possible to add a runner config file as well as shell scripts to setup and teardown the test case ([see the service example](https://code.forgejo.org/forgejo/end-to-end/src/branch/main/actions/example-service)).
+# Reporting security-related issues
 
 Sensitive security-related issues should be reported to [[email protected]](mailto:[email protected]) using [encryption](https://keyoxide.org/[email protected]).
 
-
 ## License
 
 The Forgejo runner source code is distributed under the terms of the following licenses:
@@ -36,77 +33,37 @@ The Forgejo runner is a dependency of the [setup-forgejo action](https://code.fo
 - Install [Go](https://go.dev/doc/install) and `make(1)`
 - `make build`
 
-The [test workflow](.forgejo/workflows/test.yml) is a full example that builds the binary, runs the tests and launches the runner binary against a live Forgejo instance.
-
-## Generate mocks
-
-- `make deps-tools`
-- `make generate`
-
-If there are changes, commit them to the repository.
-
-## Local debug
-
-The repositories are checked out in the same directory:
-
-- **runner**: [Forgejo runner](https://code.forgejo.org/forgejo/runner)
-- **setup-forgejo**: [setup-forgejo](https://code.forgejo.org/actions/setup-forgejo)
-
-### Install dependencies
-
-The dependencies are installed manually or with:
+## Linting
 
-```shell
-setup-forgejo/forgejo-dependencies.sh
-```
-
-### Build the Forgejo runner
-
-```shell
-cd runner ; rm -f forgejo-runner ; make forgejo-runner
-```
-
-### Launch Forgejo and the runner
+- `make lint-check`
+- `make lint` # will fix some lint errors
 
-A Forgejo instance is launched with:
+## Testing
 
-```shell
-cd setup-forgejo
-./forgejo.sh setup
-firefox $(cat forgejo-url)
-```
+The [workflow](.forgejo/workflows/test.yml) that runs in the CI uses similar commands.
 
-The user is `root` with password `admin1234`. The runner is registered with:
+### Without a Forgejo instance
 
-```
-cd setup-forgejo
-docker exec --user 1000 forgejo forgejo actions generate-runner-token > forgejo-runner-token
-../runner/forgejo-runner register --no-interactive --instance "$(cat forgejo-url)" --name runner --token $(cat forgejo-runner-token) --labels docker:docker://node:22-bookworm,self-hosted:host,lxc:lxc://debian:bookworm
-```
+- Install [Docker](https://docs.docker.com/engine/install/)
+- `make test integration-test`
 
-And launched with:
-
-```shell
-cd setup-forgejo ; ../runner/forgejo-runner --config runner-config.yml daemon
-```
+### With a Forgejo instance
 
-Note that the `runner-config.yml` is required in that particular case
-to configure the network in `bridge` mode, otherwise the runner will
-create a network that cannot reach the forgejo instance.
-
-### Try a sample workflow
-
-From the Forgejo web interface, create a repository and add the
-following to `.forgejo/workflows/try.yaml`. It will launch the job and
-the result can be observed from the `actions` tab.
-
-```yaml
-on: [push]
-jobs:
-  ls:
-    runs-on: docker
-    steps:
-      - uses: actions/checkout@v4
-      - run: |
-          ls ${{ github.workspace }}
+- Run a Forgejo instance locally (for instance at http://0.0.0.0:8080) and create as shared secret
+```sh
+export FORGEJO_RUNNER_SECRET='AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA'
+export FORGEJO_URL=http://0.0.0.0:8080
+forgejo forgejo-cli actions register --labels docker --name therunner --secret $FORGEJO_RUNNER_SECRET
 ```
+- `make test integration-test` # which will run addional tests because FORGEJO_URL is set
+
+### end-to-end
+
+- Follow the instructions from the end-to-end tests to [run actions tests locally](https://code.forgejo.org/forgejo/end-to-end#running-from-locally-built-binary).
+- `./end-to-end.sh actions_teardown` # stop the Forgejo and runner daemons running in the end-to-end environment
+- `( cd ~/clone-of-the-runner-repo ; make build ; cp forgejo-runner /tmp/forgejo-end-to-end/forgejo-runner )` # install the runner built from sources
+- `./end-to-end.sh actions_setup 13.0` # start Forgejo v13.0 and the runner daemon in the end-to-end environment
+- `./end-to-end.sh actions_verify_example echo` # run the [echo workflow](https://code.forgejo.org/forgejo/end-to-end/src/branch/main/actions/example-echo/.forgejo/workflows/test.yml)
+- `xdg-open http://127.0.0.1:3000/root/example-echo/actions/runs/1` # see the logs workflow
+- `less /tmp/forgejo-end-to-end/forgejo-runner.log` # analyze the runner logs
+- `less /tmp/forgejo-end-to-end/forgejo-work-path/log/forgejo.log` # analyze the Forgejo logs