diff --git a/docs/contributing/committing.rst b/docs/contributing/committing.rst new file mode 100644 index 0000000000..7bef3b176d --- /dev/null +++ b/docs/contributing/committing.rst @@ -0,0 +1,121 @@ +=============== +Committing code +=============== + +This section is for the committers of Wagtail, +or for anyone interested in the process of getting code committed to Wagtail. + +Code should only be committed after it has been reviewed +by at least one other reviewer or committer, +unless the change is a small documentation change or fixing a typo. + +Most code contributions will be in the form of pull requests from Github. +Pull requests should not be merged from Github though. +Instead, the code should be checked out by a committer locally, +the changes examined and rebased, +the CHANGELOG and release notes updated, +and finally the code should be pushed to the master branch. +This process is covered in more detail below. + +Check out the code locally +========================== + +If the code has been submitted as a pull request, +you should fetch the changes and check them out in your Wagtail repository. +A simple way to do this is by adding the following ``git`` alias to your ``~/.gitconfig`` (assuming ``upstream`` is ``torchbox/wagtail``): + +.. code-block:: text + + [alias] + pr = !sh -c \"git fetch upstream pull/${1}/head:pr/${1} && git checkout pr/${1}\" + +Now you can check out pull request number ``xxxx`` by running ``git pr xxxx``. + +Rebase on to master +=================== + +Now that you have the code, you should rebase the commits on to the ``master`` branch. +Rebasing is preferred over merging, +as merge commits make the commit history harder to read for small changes. + +You can fix up any small mistakes in the commits, +such as typos and formatting, as part of the rebase. +``git rebase --interactive`` is an excellent tool for this job. + +.. code-block:: sh + + # Get the latest commits from Wagtail + $ git fetch upstream + $ git checkout master + $ git merge --ff-only upstream/master + # Rebase this pull request on to master + $ git checkout pr/xxxx + $ git rebase master + # Update master to this commit + $ git checkout master + $ git merge --ff-only pr/xxxx + +Update CHANGELOG and release notes +================================== + +Every significant change to Wagtail should get an entry in the CHANGELOG, +and the release notes for the current version. + +The CHANGELOG contains a short summary of each new feature, refactoring, or bug fix in each release. +Each summary should be a single line. +Bug fixes should be grouped together at the end of the list for each release, +and be prefixed with "Fix:". +The name of the contributor should be added at the end of the summary, +in brackets, if they are not a core committer. +For example: + +.. code-block:: text + + * Fix: Tags added on the multiple image uploader are now saved correctly (Alex Smith) + +The release notes for each version contain a more detailed description of each change. +Backwards compatibility notes should also be included. +Large new features or changes should get their own section, +while smaller changes and bug fixes should be grouped together in their own section. +See previous release notes for examples. +The release notes for each version are found in ``docs/releases/x.x.x.rst``. + +If the contributor is a new person, and this is their first contribution to Wagtail, +they should be added to the ``CONTRIBUTORS.rst`` list. +Contributors are added in chronological order, +with new contributors added to the bottom of the list. +Use their preferred name. +You can usually find the name of a contributor on their Github profile. +If in doubt, or if their name is not on their profile, ask them how they want to be named. + +If the changes to be merged are small enough to be a single commit, +amend this single commit with the additions to +the CHANGELOG, release notes, and contributors: + +.. code-block:: sh + + $ git add CHANGELOG docs/releases/x.x.x.rst CONTRIBUTING.md + $ git commit --amend --no-edit + +If the changes do not fit in a single commit, make a new commit with the updates to +the CHANGELOG, release notes, and contributors. +The commit message should say ``Release notes for #xxxx``: + +.. code-block:: sh + + $ git add CHANGELOG docs/releases/x.x.x.rst CONTRIBUTING.md + $ git commit -m 'Release notes for #xxxx' + +Push to master +============== + +The changes are ready to be pushed to ``master`` now. + +.. code-block:: sh + + # Check that everything looks OK + $ git log upstream/master..master --oneline + $ git push --dry-run upstream master + # Push the commits! + $ git push upstream master + $ git branch -d pr/xxxx diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst index 76b0b61f91..386a01ae28 100644 --- a/docs/contributing/index.rst +++ b/docs/contributing/index.rst @@ -35,3 +35,4 @@ We welcome contributions to all aspects of Wagtail. If you would like to improve python_guidelines css_guidelines javascript_guidelines + committing