kopia lustrzana https://github.com/wagtail/wagtail
Add docs on committing code
Inspiration and flow from Django's `internals/contributing/committing-code` docspull/2302/head
rodzic
9d34ede16f
commit
74986f7d4d
|
@ -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
|
|
@ -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
|
||||
|
|
Ładowanie…
Reference in New Issue