2022-06-30 20:27:24 +00:00
|
|
|
# Committing code
|
2016-03-02 23:55:51 +00:00
|
|
|
|
2019-08-05 12:35:29 +00:00
|
|
|
**This section is for the core team of Wagtail, or for anyone interested in the process of getting code committed to Wagtail.**
|
2016-03-02 23:55:51 +00:00
|
|
|
|
|
|
|
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.
|
2017-02-03 09:46:15 +00:00
|
|
|
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.
|
2016-03-02 23:55:51 +00:00
|
|
|
|
|
|
|
Most code contributions will be in the form of pull requests from Github.
|
2016-11-28 01:30:44 +00:00
|
|
|
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
|
2016-11-08 09:57:15 +00:00
|
|
|
be checked out by a committer locally, the changes examined and rebased,
|
2022-06-30 20:27:24 +00:00
|
|
|
the `CHANGELOG.txt` and release notes updated,
|
|
|
|
and finally the code should be pushed to the `main` branch.
|
2016-03-02 23:55:51 +00:00
|
|
|
This process is covered in more detail below.
|
|
|
|
|
2022-06-30 20:27:24 +00:00
|
|
|
## Check out the code locally
|
2016-03-02 23:55:51 +00:00
|
|
|
|
|
|
|
If the code has been submitted as a pull request,
|
|
|
|
you should fetch the changes and check them out in your Wagtail repository.
|
2022-06-30 20:27:24 +00:00
|
|
|
A simple way to do this is by adding the following `git` alias to your `~/.gitconfig` (assuming `upstream` is `wagtail/wagtail`):
|
2016-03-02 23:55:51 +00:00
|
|
|
|
2022-06-30 20:27:24 +00:00
|
|
|
```text
|
|
|
|
[alias]
|
|
|
|
pr = !sh -c \"git fetch upstream pull/${1}/head:pr/${1} && git checkout pr/${1}\"
|
|
|
|
```
|
2016-03-02 23:55:51 +00:00
|
|
|
|
2022-06-30 20:27:24 +00:00
|
|
|
Now you can check out pull request number `xxxx` by running `git pr xxxx`.
|
2016-03-02 23:55:51 +00:00
|
|
|
|
2022-06-30 20:27:24 +00:00
|
|
|
## Rebase on to `main`
|
2016-03-02 23:55:51 +00:00
|
|
|
|
2022-06-30 20:27:24 +00:00
|
|
|
Now that you have the code, you should rebase the commits on to the `main` branch.
|
2016-03-02 23:55:51 +00:00
|
|
|
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.
|
2022-06-30 20:27:24 +00:00
|
|
|
`git rebase --interactive` is an excellent tool for this job.
|
2016-03-02 23:55:51 +00:00
|
|
|
|
2017-02-03 09:46:15 +00:00
|
|
|
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.
|
|
|
|
|
2022-10-13 06:25:19 +00:00
|
|
|
```sh
|
2022-06-30 20:27:24 +00:00
|
|
|
# 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`,
|
2016-03-02 23:55:51 +00:00
|
|
|
and the release notes for the current version.
|
|
|
|
|
2022-06-30 20:27:24 +00:00
|
|
|
The `CHANGELOG.txt` contains a short summary of each new feature, refactoring, or bug fix in each release.
|
2016-03-02 23:55:51 +00:00
|
|
|
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:".
|
2020-01-27 14:25:42 +00:00
|
|
|
The name of the contributor should be added at the end of the summary, in brackets.
|
2016-03-02 23:55:51 +00:00
|
|
|
For example:
|
|
|
|
|
2022-06-30 20:27:24 +00:00
|
|
|
```text
|
|
|
|
* Fix: Tags added on the multiple image uploader are now saved correctly (Alex Smith)
|
|
|
|
```
|
2016-03-02 23:55:51 +00:00
|
|
|
|
|
|
|
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.
|
2022-06-30 20:27:24 +00:00
|
|
|
The release notes for each version are found in `docs/releases/x.x.x.md`.
|
2016-03-02 23:55:51 +00:00
|
|
|
|
|
|
|
If the contributor is a new person, and this is their first contribution to Wagtail,
|
2022-06-30 20:27:24 +00:00
|
|
|
they should be added to the `CONTRIBUTORS.rst` list.
|
2016-03-02 23:55:51 +00:00
|
|
|
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
|
2022-06-30 20:27:24 +00:00
|
|
|
the `CHANGELOG.txt`, release notes, and contributors:
|
2016-03-02 23:55:51 +00:00
|
|
|
|
2022-10-13 06:25:19 +00:00
|
|
|
```sh
|
2022-06-30 20:27:24 +00:00
|
|
|
git add CHANGELOG.txt docs/releases/x.x.x.md CONTRIBUTORS.md
|
|
|
|
git commit --amend --no-edit
|
|
|
|
```
|
2016-03-02 23:55:51 +00:00
|
|
|
|
|
|
|
If the changes do not fit in a single commit, make a new commit with the updates to
|
2022-06-30 20:27:24 +00:00
|
|
|
the `CHANGELOG.txt`, release notes, and contributors.
|
|
|
|
The commit message should say `Release notes for #xxxx`:
|
2016-03-02 23:55:51 +00:00
|
|
|
|
2022-10-13 06:25:19 +00:00
|
|
|
```sh
|
2022-06-30 20:27:24 +00:00
|
|
|
git add CHANGELOG.txt docs/releases/x.x.x.md CONTRIBUTORS.md
|
|
|
|
git commit -m 'Release notes for #xxxx'
|
|
|
|
```
|
2016-03-02 23:55:51 +00:00
|
|
|
|
2022-06-30 20:27:24 +00:00
|
|
|
## Push to `main`
|
2016-03-02 23:55:51 +00:00
|
|
|
|
2022-06-30 20:27:24 +00:00
|
|
|
The changes are ready to be pushed to `main` now.
|
2016-03-02 23:55:51 +00:00
|
|
|
|
2022-10-13 06:25:19 +00:00
|
|
|
```sh
|
2022-06-30 20:27:24 +00:00
|
|
|
# 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
|
|
|
|
```
|
2016-03-02 23:55:51 +00:00
|
|
|
|
2022-06-30 20:27:24 +00:00
|
|
|
## When you have made a mistake
|
2017-02-03 09:46:15 +00:00
|
|
|
|
|
|
|
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.
|
2020-05-14 18:56:41 +00:00
|
|
|
|
2022-06-30 20:27:24 +00:00
|
|
|
## Add commits to someone else's pull request
|
2020-05-14 18:56:41 +00:00
|
|
|
|
|
|
|
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:
|
|
|
|
|
2022-10-13 06:25:19 +00:00
|
|
|
```sh
|
2022-06-30 20:27:24 +00:00
|
|
|
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
|
|
|
|
```
|