diff --git a/content/forking-workflow.md b/content/forking-workflow.md index c5ed1f1..5594197 100644 --- a/content/forking-workflow.md +++ b/content/forking-workflow.md @@ -86,6 +86,115 @@ accept modifications without having to grant write access to others. ::: -## Solution and walk-through +## Help and discussion -We will add this before the lesson. + +### Opening a pull request towards the upstream repository + +We have learned in the previous episode that pull requests are always from +branch to branch. But the branch can be in a different repository. + +When you open a pull request in a fork, by default GitHub will suggest to +direct it towards the default branch of the upstream repository. + +This can be changed and it should always be verified, but in this case this is +exactly what we want to do, from fork towards upstream: +:::{figure} img/forking-workflow/pull-request-form.png +:width: 100% +:class: with-border +:alt: Screenshot of a pull request from fork towards upstream +:::: + + +### Pull requests can be coupled with automated testing + +We added an automated test here just for fun and so that you see that this is +possible to do. + +In this exercise, the test is silly. It will check whether the recipe contains +both an ingredients and an instructions section. + +In this example the test failed: +:::{figure} img/forking-workflow/all-checks-failed.png +:width: 60% +:class: with-border +:alt: Screenshot of a failed test in a pull request +:::: + +Click on the "Details" link to see the details of the failed test: +:::{figure} img/forking-workflow/check-details.png +:width: 60% +:class: with-border +:alt: Screenshot of details why the test failed +:::: + +**How can this be useful?** +- The project can define what kind of tests are expected to pass before a pull + request can be merged. +- The reviewer can see the results of the tests, without having to run them + locally. + +**How does it work?** +- We added a [GitHub Actions workflow](https://github.com/coderefinery/recipe-book-template/blob/main/.github/workflows/check-recipes.yml) + to automatically run on each push or pull request towards the `main` branch. + +What tests or steps can you image for your project to run automatically with +each pull request? + + +### How to update your fork with changes from upstream + +This used to be difficult but now it is two mouse clicks. + +Navigate to your fork and notice how GitHub tells you that your fork is behind. +In my case, it is 9 commits behind upstream. To fix this, click on "Sync fork" +and then "Update branch": +:::{figure} img/forking-workflow/sync-fork.png +:width: 80% +:class: with-border +:alt: Screenshot on GitHub fork page showing that the fork is behind +:::: + +After the update my "branch is up to date" with the upstream repository: +:::{figure} img/forking-workflow/fork-after-update.png +:width: 80% +:class: with-border +:alt: Screenshot on GitHub after fork has been updated +:::: + + +### How to approach other people’s repositories with ideas, changes, and requests + +**Contributing very minor changes** +- Clone or fork+clone repository +- Create a branch +- Commit and push change +- Open a pull request or merge request + +**If you observe an issue and have an idea how to fix it** +- Open an issue in the repository you wish to contribute to +- Describe the problem +- If you have a suggestion on how to fix it, describe your suggestion +- Possibly **discuss and get feedback** +- If you are working on the fix, indicate it in the issue so that others know that somebody is working on it and who is working on it +- Submit your fix as pull request or merge request which references/closes the issue + +:::{admonition} Motivation +- **Inform others about an observed problem** +- Make it clear whether this issue is up for grabs or already being worked on +::: + +**If you have an idea for a new feature** +- Open an issue in the repository you wish to contribute to +- In the issue, write a short proposal for your suggested change or new feature +- Motivate why and how you wish to do this +- Also indicate where you are unsure and where you would like feedback +- **Discuss and get feedback before you code** +- Once you start coding, indicate that you are working on it +- Once you are done, submit your new feature as pull request or merge request which references/closes the issue/proposal + +:::{admonition} Motivation +- **Get agreement and feedback before writing 5000 lines of code** which might be rejected +- If we later wonder why something was done, we have the issue/proposal as + reference and can read up on the reasoning behind a code change +::: diff --git a/content/img/forking-workflow/all-checks-failed.png b/content/img/forking-workflow/all-checks-failed.png new file mode 100644 index 0000000..5175684 Binary files /dev/null and b/content/img/forking-workflow/all-checks-failed.png differ diff --git a/content/img/forking-workflow/check-details.png b/content/img/forking-workflow/check-details.png new file mode 100644 index 0000000..456a247 Binary files /dev/null and b/content/img/forking-workflow/check-details.png differ diff --git a/content/img/forking-workflow/fork-after-update.png b/content/img/forking-workflow/fork-after-update.png new file mode 100644 index 0000000..38fc8c6 Binary files /dev/null and b/content/img/forking-workflow/fork-after-update.png differ diff --git a/content/img/forking-workflow/pull-request-form.png b/content/img/forking-workflow/pull-request-form.png new file mode 100644 index 0000000..c6c6af8 Binary files /dev/null and b/content/img/forking-workflow/pull-request-form.png differ diff --git a/content/img/forking-workflow/sync-fork.png b/content/img/forking-workflow/sync-fork.png new file mode 100644 index 0000000..848a054 Binary files /dev/null and b/content/img/forking-workflow/sync-fork.png differ