Forking a plugin, creating a pull request and keeping your plugin fork repo up to date (correctly)
-
Contributions to our plugins from within and from outside the german-speaking higher education Moodle community are highly appreciated. We always appreciate if developers take the time to improve and extend our plugins in any way.
-
Every community member is invited to create patches for our plugins and submit them as pull request. However, during the lifetime of such a pull request, things can work well or not. To help you and us with the process of submitting pull requests, we built the following instruction for developers.
-
The following steps use the Boost Union plugin as example and the plugin is checked out to your computer's Desktop folder. Please adapt the example paths to the plugin which you want to extend and the path where your local Moodle codebase is located.
-
Create a Github account (if you haven't got one already) and login with this account on github.com. (Sidenote: Please use a personal Github account and not an organization account as organization accounts currently do not provide the possibility to allow the pull request reviewer to push changes to the fork which would case more effort for us later down the road).
-
Go to the plugin repository on Github:
https://github.com/moodle-an-hochschulen/moodle-theme_boost_union -
Fork the repository to your own Github account (by clicking the 'Fork' button in the top right corner or by going to this URL directly):
https://github.com/moodle-an-hochschulen/moodle-theme_boost_union/fork -
Clone your fork to your computer:
cd ~/Desktop\
git clone [email protected]:bdecentgmbh/moodle-theme_boost_union.git -
Go to the repo on your computer:
cd ~/Desktop/moodle-theme_boost_union/ -
Add the upstream repo as remote repo:
git remote add upstream [email protected]:moodle-an-hochschulen/moodle-theme_boost_union.git
These steps are necessary every time you want to update (the master branch of) your fork to the upstream version:
-
Go to the repo on your computer:
cd ~/Desktop/moodle-theme_boost_union -
Fetch the status from upstream:
git fetch upstream -
Checkout the master branch locally:
git checkout master -
Reset your local master branch to the upstream master branch:
git reset --hard upstream/master -
Push the version back to your fork, overwriting any changes in your master branch:
git push origin master --force
- Every issue / task should be solved in one commit. Do not combine more than one issue in one commit to ease the reviewer's life.
- Every issue / task should be provided in a dedicated branch which will then be contributed as a dedicated pull request in Github. Only if you are dealing with multiple issues / tasks at once which target the same code or files, you can combine several commits in the same branch and pull request.
- The reviewers are not working fulltime on the plugins and reviewing pull requests get more complicated the bigger the pull requests are. Against this background, please strive to keep the individual pull requests as concise as possible.
- When building patches, please respect the existing code structures. Do not change existing code structures if this is not needed for your patch. If you spot anything in the existing codebase during your work which should be changed, please create a follow-up issue on Github instead.
- All patches have to target the upstream master branch. This is the development version of the plugin. After your PR is merged, the plugin maintainers will make sure that the patch is backported to the MOODLE_4**_STABLE branches.
- The reviewers have a checklist which can be found on https://github.com/moodle-an-hochschulen/moodle-plugin-maintaining/wiki/Check-list-for-peer-reviewing-patches-and-pull-requests. Please get familiar with this checklist. The reviewer will appreciate if you adhere these rules yourself in your patches.
-
Go to the repo on your computer:
cd ~/Desktop/moodle-theme_boost_union/ -
Checkout the master branch:
git checkout master -
Create a branch which is ideally labeled with the issue number:
git checkout -b issue-42 -
Do your development, adhering the abovementioned checklist.
-
Commit your changes, ideally using the issue title as commit message and linking your issue in the PR title:
git add *
git commit -m "Feature: Provide the ultimate user experience, resolves #42" -
Push your feature branch to your fork repo:
git push origin issue-42 -
Go to the plugin repo (our plugin repo, not your fork) on Github: https://github.com/moodle-an-hochschulen/moodle-theme_boost_union
-
Create a pull request for this branch (by clicking the 'Pull request' button in the navigation bar or by going to this URL directly):
https://github.com/moodle-an-hochschulen/moodle-theme_boost_union/pulls -
Make sure that our master branch is selected as the pull request's
baseand your feature branch is selected ascomparebranch. -
Provide any further information that is relevant for peer review and not yet mentioned in the linked issue as a comment in the pull request
-
Make sure that the 'Allow edits by maintainers' checkbox is checked when creating the pull request. Otherwise, the peer reviewer would not be able to push any review changes to the pull request and the communication overhead increases
-
Submit your pull request in draft status to run the automated checks and review the results
-
After you have created the pull request, wait for the automated checks (with Github actions) to complete. You will see the result in the pull request. If the checks are green, everything is fine. If the checks are red, go ahead and try to fix them directly by pushing refined patches to your branch. In the end, it's your job to make sure that the checks are green.
-
If all checks pass (or if you are unable to resolve the failing steps without any help of the review team), mark the PR as 'ready for review', in the request itself, by using the "Ready for review" titled button.
It might take some time until a reviewer can review and merge your pull request. During this time, other pull requests and patches may be merged into the upstream master branch.
In these cases, you should rebase your branch to the latest upstream master. To rebase your branch, do NOT use any "update this fork" features in Github or similar tempting easy-to-use rebasing approaches as they will end up in a improper commit history.
This is how rebasing your branch is done properly:
-
Go to the repo on your computer:
cd ~/Desktop/moodle-theme_boost_union -
Fetch the status from upstream:
git fetch upstream -
Checkout your feature branch locally
git checkout issue-42 -
Rebase your local feature branch to the upstream master branch
git rebase upstream/master -
If there are any conflicts during the rebase, fix them in the affected files, then run
git add affected-file
and then rungit rebase --continue -
Push your feature branch back to your fork, overwriting any changes in your branch
git push origin issue-42 --force -
After these steps, the Github pull request gets updated automatically and the automated checks in the pull request will run again. Watch out for the results of the checks again.
-
When the reviewer reviews the pull request and is not able to directly merge it for whatever reason, he will leave comments in the pull request.
-
Such a comment could either be a general question / discussion on the pull request's main page.
-
Such a comment could also be directed to a particular code area. Such comments are also visible on the pull request's main page, but you will also see it on Github's detail view of the patch.
-
It's your duty to watch the pull request and answer / handle any questions of the reviewer in reasonable time.
-
As soon as the reviewer is happy with the pull request, he will merge it. At this point, the pull request is closed and you can congratulate yourself having done a great job!