From 587c0591f2fbd5762d6456fbfa82c598b7219f28 Mon Sep 17 00:00:00 2001 From: Felix Seifert Date: Tue, 5 Sep 2023 21:28:24 +0200 Subject: [PATCH] Describe how our tests can interfere with development and might require updates --- DEVELOPING.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 DEVELOPING.md diff --git a/DEVELOPING.md b/DEVELOPING.md new file mode 100644 index 0000000..d8aeb9f --- /dev/null +++ b/DEVELOPING.md @@ -0,0 +1,30 @@ +# Dev Guide + +## Automated Tests + +Before merging any PR into our `main` branch, we run automated tests on your modified source code. Besides some platform +independent unit tests, several of these tests are platform dependent and require to be executed remotely on the GitHub +build agents. These tests generate roadmaps on different OSs with your modified code and compare them to how these +roadmaps should look like. + +All the required tests are triggered automatically once you open or change a PR. To verify that the `main` branch hosts +a correct version of the code, any merge to the `main` branch also triggers the tests. + +### Change Example Roadmaps + +Usually, the appearance of the newly generated roadmaps should not change between different releases of `Roadmapper`. +However, some code changes purposefully change the appearance of the generated roadmaps. To let our tests succeed with +the new version, we will then have to generate new example roadmaps on the GitHub build agents which accommodate these +changes. + +To generate these example roadmaps on different GitHub build agents, we have the manual workflow +[generate_examples](.github/workflows/generate_examples.yaml). We can trigger it manually through the +[Actions tab](https://github.com/csgoh/roadmapper/actions/workflows/generate_examples.yaml). In the dropdown to trigger +a run of the workflow, we can also select on which branch the workflow should run, i.e. we can influence which code +should be used to generate the example roadmaps. + +As we usually want to generate new example roadmaps for code which is not present on the `main` branch, we have to run +the workflow on the branch where the respective code changes are present. When ran, the workflow produces artifacts for +the different platforms which contain the example roadmaps. These artifacts can be found in the summary of the +respective workflow run. To use these new example roadmaps, we should download them and commit them manually to the +directory [`src/tests/example_roadmaps`](src/tests/example_roadmaps). \ No newline at end of file