kopia lustrzana https://github.com/wagtail/wagtail
161 wiersze
6.1 KiB
Markdown
161 wiersze
6.1 KiB
Markdown
|
===============
|
||
|
Committing code
|
||
|
===============
|
||
|
|
||
|
**This section is for the core team 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.
|
||
|
If additional code changes are made after the review, it is OK to commit them
|
||
|
without further review if they are uncontroversial and small enough that
|
||
|
there is minimal chance of introducing new bugs.
|
||
|
|
||
|
Most code contributions will be in the form of pull requests from Github.
|
||
|
Pull requests should not be merged from Github, apart from small documentation fixes,
|
||
|
which can be merged with the 'Squash and merge' option. Instead, the code should
|
||
|
be checked out by a committer locally, the changes examined and rebased,
|
||
|
the ``CHANGELOG.txt`` and release notes updated,
|
||
|
and finally the code should be pushed to the ``main`` 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 ``wagtail/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 ``main``
|
||
|
=====================
|
||
|
|
||
|
Now that you have the code, you should rebase the commits on to the ``main`` 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.
|
||
|
|
||
|
Ideally, use this as an opportunity to squash the changes to a few commits, so
|
||
|
each commit is making a single meaningful change (and not breaking anything).
|
||
|
If this is not possible because of the nature of the changes, it's acceptable
|
||
|
to either squash into a commit or leave all commits unsquashed,
|
||
|
depending on which will be more readable in the commit history.
|
||
|
|
||
|
.. code-block:: console
|
||
|
|
||
|
$ # Get the latest commits from Wagtail
|
||
|
$ git fetch upstream
|
||
|
$ git checkout main
|
||
|
$ git merge --ff-only upstream/main
|
||
|
$ # Rebase this pull request on to main
|
||
|
$ git checkout pr/xxxx
|
||
|
$ git rebase main
|
||
|
$ # Update main to this commit
|
||
|
$ git checkout main
|
||
|
$ git merge --ff-only pr/xxxx
|
||
|
|
||
|
Update ``CHANGELOG.txt`` and release notes
|
||
|
==========================================
|
||
|
|
||
|
.. note::
|
||
|
|
||
|
This should only be done by core committers, once the changes have been reviewed and accepted.
|
||
|
|
||
|
Every significant change to Wagtail should get an entry in the ``CHANGELOG.txt``,
|
||
|
and the release notes for the current version.
|
||
|
|
||
|
The ``CHANGELOG.txt`` 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.
|
||
|
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.txt``, release notes, and contributors:
|
||
|
|
||
|
.. code-block:: console
|
||
|
|
||
|
$ git add CHANGELOG.txt docs/releases/x.x.x.rst CONTRIBUTORS.rst
|
||
|
$ 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.txt``, release notes, and contributors.
|
||
|
The commit message should say ``Release notes for #xxxx``:
|
||
|
|
||
|
.. code-block:: console
|
||
|
|
||
|
$ git add CHANGELOG.txt docs/releases/x.x.x.rst CONTRIBUTORS.rst
|
||
|
$ git commit -m 'Release notes for #xxxx'
|
||
|
|
||
|
Push to ``main``
|
||
|
================
|
||
|
|
||
|
The changes are ready to be pushed to ``main`` now.
|
||
|
|
||
|
.. code-block:: console
|
||
|
|
||
|
$ # Check that everything looks OK
|
||
|
$ git log upstream/main..main --oneline
|
||
|
$ git push --dry-run upstream main
|
||
|
$ # Push the commits!
|
||
|
$ git push upstream main
|
||
|
$ git branch -d pr/xxxx
|
||
|
|
||
|
When you have made a mistake
|
||
|
============================
|
||
|
|
||
|
It's ok! Everyone makes mistakes. If you realise that recent merged changes
|
||
|
have a negative impact, create a new pull request with a revert of the changes
|
||
|
and merge it without waiting for a review. The PR will serve as additional
|
||
|
documentation for the changes, and will run through the CI tests.
|
||
|
|
||
|
|
||
|
Add commits to someone else's pull request
|
||
|
==========================================
|
||
|
|
||
|
Github users with write access to wagtail/wagtail (core members) can add
|
||
|
commits to the pull request branch of the contributor.
|
||
|
|
||
|
Given that the contributor username is johndoe and his pull request branch is called foo:
|
||
|
|
||
|
.. code-block:: console
|
||
|
|
||
|
$ git clone git@github.com:wagtail/wagtail.git
|
||
|
$ cd wagtail
|
||
|
$ git remote add johndoe git@github.com:johndoe/wagtail.git
|
||
|
$ git fetch johndoe foo
|
||
|
$ git checkout johndoe/foo
|
||
|
# Make changes
|
||
|
# Commit changes
|
||
|
$ git push johndoe HEAD:foo
|