Your first contribution¶

0. Understand your motivations¶

Before you start contributing to Wagtail, take a moment to think about why you want to do it. If your only goal is to add a “first contribution” to your resume (or if you’re just looking for a quick win) you might be better off doing a boot-camp or an online tutorial.

Contributing to open source projects takes time and effort, but it can also help you become a better developer and learn new skills. However, it’s important to know that it might be harder and slower than following a training course. That said, contributing to open source is worth it if you’re willing to take the time to do things well.

One thing to keep in mind is that “scratching your own itch” can be a great motivator for contributing to open source. If you’re interested in the CMS space or the programming languages used in this project, you’ll be more likely to stick with it over the long term.

1. Understanding what Wagtail is¶

Before you start contributing to Wagtail, it’s important to understand what it is and how it works. Wagtail is a content management system (CMS) used for building websites. Unlike other CMSs, it requires some development time to build up the models and supporting code to use as a CMS. Additionally, Wagtail is built on top of another framework called Django, which is a Python web framework. This might be confusing at first, but it provides a powerful way to create custom systems for developers to build with.

To get started, we recommend reading the the Zen of Wagtail, which provides a good introduction to the project. You might also want to read the Django overview to understand what Django provides. To get a sense of how Wagtail fits into the CMS landscape, you can search online for articles that compare WordPress to Wagtail or list the top open source CMSs. Finally, reading some of the Wagtail Guide will give you a better understanding of how the CMS works for everyday users.

-   [ ] Read the Zen of Wagtail
-   [ ] Read the Django Overview
-   [ ] Search online for one or two articles that 'compare Wordpress to Wagtail' or 'top ten open source CMS' and read about the CMS landscape
-   [ ] Read some of the Wagtail Guide

2. Joining the community¶

Make an account on Wagtail Slack server, this is the way many of the community interact day to day. Introduce yourself on #new-contributors and join some of the other channels, remember to keep your intro short and be nice to others. After this, join GitHub and set up your profile. It’s really helpful to the community if your name can be added to your profiles in both communities and an image. It does not have to be your public name or a real image if you want to keep that private but please avoid it staying as the ‘default avatar’.

You may also want to join StackOverflow and follow the Wagtail tag, this way you can upvote great answers to questions you have or maybe consider contributing answers yourself.

-   [ ] Read the community guidelines
-   [ ] Join GitHub
-   [ ] Add your preferred name and image to your GitHub profile
-   [ ] Join Slack
-   [ ] Add your preferred name, timezone and image to your Slack profile
-   [ ] Introduce yourself in `#new-contributors` in Slack
-   [ ] Join the `#support` channel in Slack
-   [ ] _Optional_ Join StackOverflow

3. Before contributing code¶

Firstly, it is important to be able to understand how to build with Wagtail before you can understand how to contribute to Wagtail. Take the time to do the full Wagtail getting started tutorial without focusing yet on how to contribute code but instead how to use Wagtail to build your own basic demo website. This will require you to have Python and other dependencies installed on your machine and may not be easy the first time, but keep at it and ask questions if you get stuck.

Remember that there are many other ways to contribute, such as answering questions in StackOverflow or #support, contributing to one of the other packages or even the Wagtail user guide. Sometimes, it’s best to get started with a non-code contribution to get a feel for Wagtail’s code or the CMS interface.

Issue tracking, reading and triage is a critical part of contributing code and it is recommended that you read the issue tracking guide in full. This will help you understand how to find issues to work on and how to support the team with triaging issues.

- [ ] Do the Wagtail tutorial
- [ ] Look at the Wagtail organisation on GitHub, take note of any interesting projects
- [ ] Read through the Issue Tracking section in the docs
- [ ] Give a go at a non-code contribution

4. Setting up your development environment¶

Many contribution sections gloss over the mammoth task that can be a single line in the documentation similar to “fork the code and get it running locally”. This, on its own, can be a daunting task if you are just getting started. This is why it’s best to have done the Wagtail tutorial before this step so you have run into and hopefully solved many of the normal developer environment issues.

First, create a clone of Wagtail on your GitHub account (see below for more details).

Read (in full) the Development guide. This will walk you through how to get your code running locally so you can contribute. It’s strongly recommended to use the Vagrant or Docker setups, especially if you are working on Windows.

- [ ] Install `git` (if not on your machine)
- [ ] Install a code editor/IDE (we recommend VSCode)
- [ ] Install the dependencies set out in the development guide
- [ ] Follow the development guide
- [ ] Make a change to the `wagtail/admin/templates/wagtailadmin/home.html` template file and confirm you can see the changes on the Wagtail dashboard (home) page
- [ ] Add a `console.log` statement to `client/src/entrypoints/admin/wagtailadmin.js` and confirm you can see the logging in the browser

5. Finding an issue¶

Hopefully, at this point, you have a good sense of the purpose of the project and are still keen to contribute.

Once you have the code forked and running locally, you will probably want to start looking for what to contribute.

Finding something to contribute is not always easy, especially if you are new to the project. Once you have a few candidate issues to investigate, be sure to read the entire issue description, all comments and all linked issues or pull requests. You may often find that someone else has started or finished the issue. Sometimes there are clarifications in the comments about how to approach the problem or whether the problem is even something worth solving.

If an issue has a pull request linked and not yet merged read that pull request and the discussion on it. Maybe the previous contributor got stuck or lost momentum, in which case you could pick up where they left off (assuming it’s been enough time). If you have an idea about how to solve a problem, just add a comment with a suggestion, we should all aim to help each other out.

If the issue is labelled good-first-issue, that usually means it is smaller and good for first time contributors. There are no problems with finding other issues to contribute to, have a search around and see what you can help with.

Finally, before ‘claiming’ check you can do the following;

-   [ ] Confirm that there is not someone actively working on it (no recent PR or comments in the last ~2 months)
-   [ ] Ensure you can reproduce the problem/scenario in your local version of Wagtail
-   [ ] Ensure that you feel confident to write a unit test (if it's a code change) to validate that the solution **is** implemented

6. Contributing a solution¶

Important: We only use GitHub’s issue assignment feature to members of the Wagtail core team. If an issue is not assigned to anyone, feel free to work on it, no need to ask “please assign me this issue”.

If you feel ready to contribute a solution, now is a good time to add a comment to the issue describing your intention to do so, to prevent duplicating efforts. Instead of asking “please assign me this issue”, write something similar to the following:

If it’s just a documentation request, you may refine this comment to explain where you plan to add the section in the documentation.

- [ ] After feeling confident about a solution, add a comment to the issue
- [ ] Create a new branch off `main` to track your work separate from the main branch
- [ ] Keep the changes focused towards your goal, asking questions on the issue if direction is needed
- [ ] Write unit tests

7. Submitting a Pull Request¶

A pull request that has the title ‘fixes issue’ is unhelpful at best, and spammy at worst. Take a few moments to think about how to give your change a title. Communicate (in a few words) the problem solved or feature added or bug fixed. Instead of ‘Fixes 10423’, use words and write a title ‘Fixes documentation dark mode refresh issue’. No one in a project knows that issue 10423 is that one about the documentation dark mode refresh issue.

Please try to add a proper title when you create the pull request. This will ensure that any notifications that go out to the team have the a suitable title from the start.

Referencing the issue being fixed within the pull request description is just as important as a good title. A pull request without a description is very difficult to review. Adding a note similar to fixes #1234 in your description message will let GitHub know that the change is for that issue. Add some context and some steps to reproduce the issue or scenario.

If the change is visual it’s strongly recommended to add before and after screenshots. This helps you confirm the change has worked and also helps reviewers understand the change made.

It is often good to write yourself a checklist for any pull request and fill in the gaps. Remember that the Pull Request template is there for a reason so please use that checklist also.

-   [ ] Small description of the solution, one sentence.
-   [ ] Link to issue/s that should be resolved if this pull request gets merged.
-   [ ] Questions or assumptions, maybe you made an assumption we no longer support IE11 with your CSS change, if it's not in the docs - write the assumption down.
-   [ ] Details - additional details, context or links that help the reviewer understand the pull request.
-   [ ] Screenshots - added before and after the change has been applied.
-   [ ] Browser and accessibility checks done, or not done. Added to the description.

8. Next steps¶

When you take time to contribute out of your own personal time, or even that from your paid employer, it can be very frustrating when a pull request does not get reviewed. It is best to temper your expectations with this process and remember that many people on the other side of this are also volunteers or have limited time to prioritise.

It is best to celebrate your accomplishment at this point even if your pull request never gets merged. It’s good to balance that with an eagerness about getting your amazing fix in place to help people who use the project. Balancing this tension is hard, but the unhelpful thing to do is give up and never contribute or decide that you won’t respond to feedback because it came too late.

Remember that it is OK to move on and try something else. Try a different issue or project or area of the code. Don’t just sit waiting for a response on the one thing you did before looking at other challenges.

How can I start contributing?¶

• Ideally, read this guide in full, otherwise see some quick start tips.

• Start simple - pick something small first. The good first issue label is a good place to look.

• Read the entire issue, all comments (links) and related issues.

• Someone may have started work (that work may have stalled).

• Check if assigned, we do not usually use that unless assigned to someone within the core team.

If you have done all of that and think you can give it a go just a comment with something like ‘I will give this a go’, no need to ask for permission.

Do I need to ask for permission to work on an issue?¶

No. However, check if there is an existing pull request (PR). If there is nothing, you can optionally add a comment mentioning that you’re starting work on it.

What should I include in my pull request (PR)¶

0. The fix or feature you are working on

1. Tests

2. Linted code (we make use of pre-commit. You can run all formatting with make format)

3. Updated documentation where relevant (such as when adding a new feature)

What if I fix multiple issues in the same pull request (PR)¶

It is best to avoid fixing more than one issue in a single pull request, unless you are a core contributor or there is a clear plan that involves fixing multiple things at once. Even then, it is usually a bad idea as it makes it harder for your pull request to be reviewed and it may never get merged as it’s too complex. This is especially true for completely unrelated issues such as a documentation fix for translators and a bug fix for StreamField. It is always best to create two branches and then two separate pull requests.

When do I need to write unit tests for a pull request (PR)?¶

Unless you are updating the documentation or only making visual style changes, your Pull Request should contain tests.

If you are new to writing tests in Django, start by reading the Django documentation on testing. Re-read the Wagtail documentation notes on testing and have a look at existing tests.

Note that the JavaScript testing is not as robust as the Python testing, if possible at least attempt to add some basic JS tests to new behaviour.

Where can I get help with my pull request (PR)?¶

The #new-contributors channel in Slack is the best place to get started with support for contributing code, especially for help with the process of setting up a dev environment and creating a PR.

There is also the more recently created #development channel for advice on understanding and getting around the Wagtail code-base specifically. Finally, if you have a general problem with understanding how to do something in Wagtail itself or with a specific feature, then #support can be used.

What if there is already an open pull request (PR)?¶

Be sure to always read the issue in full and review all links, sometimes there may already be an open pull request for the same issue. To avoid duplicating efforts it would be best to see if that pull request is close to ready and then move on to something else. Alternatively, if it has been a long enough amount of time, you may want to pick up the code and build on it to get it finished or ask if they need help.

Can I just use Gitpod to develop¶

While Gitpod is great for some small scale Pull Requests, it will not be a suitable tool for complex contributions and it’s best to take the time to set up a fully functional development environment so you can manage branches and ongoing commits to one branch.

Here are some links for using Gitpod with the Wagtail packages:

• Bakerydemo Gitpod instructions

• Wagtail Gitpod – Wagtail development setup in one click

How can I be assigned an issue to contribute to¶

We only use GitHub’s issue assignment feature to members of the Wagtail core team for when tasks are being planned as part of core roadmap features or when being used for a specific internship program. If an issue is not assigned to anyone, feel free to work on it, there is no need to ask to be assigned the issue.

Instead, review the issue, understand it and if you feel you can contribute you can just raise a Pull Request, or add a comment that you are taking a look at this. There are no strict claiming or reserving rules in place, anyone is free to work on any issue, but try to avoid double effort if someone has already got a Pull Request underway.

Inspiration for this content¶

Some great further reading also

• 5 simple ways anyone can contribute to Wagtail

• Ten tasty ingredients for a delicious pull request

• Preparing a Gourmet Pull Request

• Zulip’s contributor guide

• Documentation for absolute beginners to software development (discussion)

• New contributor FAQ