첫 기여

이 페이지는 Wagtail에 기여를 시작하는 방법에 대한 단계별 가이드입니다. 일반적으로 오픈 소스에 처음 입문하거나 공유 팀을 위한 코드 작성 경험이 적은 개발자에게 권장됩니다.

이것은 긴 가이드입니다 - 모든 단계를 한 번에 따르거나 완벽하게 수행하는 것에 대해 걱정하지 마세요. 커뮤니티에는 도움을 줄 많은 사람들이 있지만, 시간을 내어 스스로 읽고 이해할 수 있다면 훨씬 더 강력한 개발자가 될 것입니다.

각 섹션에는 개요와 함께 소개가 있으며, 하나씩 확인할 수 있도록 복사하여 붙여넣을 수 있는 체크리스트가 있습니다. 읽을 준비를 하세요, 앞으로 읽을 내용이 많습니다.

참고

0-6단계를 완료하기 전에 이슈를 ‘요청’하는 것을 피하세요. 이는 여러분이 기여할 수 있는 것을 과도하게 약속하지 않도록 돕고, 실제로 기여할 준비가 되었을 때 커뮤니티가 여러분을 지원하는 데 도움이 됩니다. 이슈가 ‘소진’될까 걱정하지 마세요 - 소프트웨어 개발은 끝없는 프랙탈과 같아서, 항상 도울 일이 더 많습니다.

가이드

0. 자신의 동기 이해하기

Wagtail에 기여하기 전에, 왜 그것을 하고 싶은지에 대해 잠시 생각해보세요. 만약 여러분의 유일한 목표가 이력서에 “첫 기여”를 추가하는 것이거나 (또는 단지 빠른 성공을 찾고 있다면) 부트캠프나 온라인 튜토리얼을 하는 것이 더 나을 수 있습니다.

오픈 소스 프로젝트에 기여하는 것은 시간과 노력이 필요하지만, 더 나은 개발자가 되고 새로운 기술을 배우는 데 도움이 될 수도 있습니다. 그러나 훈련 과정을 따르는 것보다 더 어렵고 느릴 수 있다는 것을 아는 것이 중요합니다. 그렇긴 하지만, 시간을 내어 일을 잘 하려는 의지가 있다면 오픈 소스에 기여하는 것은 가치가 있습니다.

명심해야 할 한 가지는 “자신의 가려운 곳을 긁는 것”이 오픈 소스에 기여하는 데 큰 동기 부여가 될 수 있다는 것입니다. 이 프로젝트에서 사용되는 CMS 분야나 프로그래밍 언어에 관심이 있다면, 장기적으로 계속 참여할 가능성이 더 높습니다.

1. Wagtail이 무엇인지 이해하기

Wagtail에 기여하기 전에, 그것이 무엇이고 어떻게 작동하는지 이해하는 것이 중요합니다. Wagtail은 웹사이트를 구축하는 데 사용되는 콘텐츠 관리 시스템(CMS)입니다. 다른 CMS와 달리, CMS로 사용하기 위한 모델과 지원 코드를 구축하는 데 약간의 개발 시간이 필요합니다. 또한, Wagtail은 Python 웹 프레임워크인 Django라는 다른 프레임워크 위에 구축됩니다. 이것은 처음에는 혼란스러울 수 있지만, 개발자들이 구축할 수 있는 맞춤형 시스템을 만드는 강력한 방법을 제공합니다.

시작하려면, 프로젝트에 대한 좋은 소개를 제공하는 Wagtail의 선(The Zen of Wagtail)을 읽는 것을 추천합니다. 또한 Django가 무엇을 제공하는지 이해하기 위해 Django 개요를 읽고 싶을 수도 있습니다. Wagtail이 CMS 환경에서 어떻게 자리 잡고 있는지 감을 잡으려면, WordPress와 Wagtail을 비교하거나 상위 오픈 소스 CMS를 나열하는 기사를 온라인에서 검색할 수 있습니다. 마지막으로, Wagtail 가이드의 일부를 읽으면 일상적인 사용자를 위해 CMS가 어떻게 작동하는지 더 잘 이해할 수 있습니다.

참고

아래는 체크리스트입니다. 이 가이드를 진행하면서 자신을 위해 복사할 수 있는 많은 체크리스트가 있습니다.

-   [ ] Wagtail의 선 읽기
-   [ ] Django 개요 읽기
-   [ ] 'WordPress와 Wagtail 비교' 또는 '상위 10개 오픈소스 CMS'와 같은 기사를 온라인에서 한두 개 검색하여 CMS 환경에 대해 읽어보기
-   [ ] Wagtail 가이드 일부 읽기

2. 커뮤니티 참여하기

Wagtail Slack 서버에 계정을 만드세요. 이것은 많은 커뮤니티 구성원들이 매일 소통하는 방법입니다. #new-contributors 채널에서 자신을 소개하고 다른 채널에도 참여하세요. 소개는 짧게 하고 다른 사람들에게 친절하게 대하는 것을 잊지 마세요. 그런 다음, GitHub에 가입하고 프로필을 설정하세요. 두 커뮤니티의 프로필에 이름을 추가하고 이미지를 넣으면 커뮤니티에 정말 도움이 됩니다. 사생활을 보호하고 싶다면 공개 이름이나 실제 이미지가 아니어도 되지만, ‘기본 아바타’로 두는 것은 피해주세요.

StackOverflow에 가입하고 Wagtail 태그를 팔로우하고 싶을 수도 있습니다. 이렇게 하면 궁금한 질문에 대한 훌륭한 답변에 찬성표를 누르거나 직접 답변을 기여하는 것을 고려할 수 있습니다. 시작하기 전에 커뮤니티 가이드라인을 검토하여 참여에 대한 기대치를 파악하세요.

체크리스트

-   [ ] 커뮤니티 가이드라인 읽기
-   [ ] GitHub 가입하기
-   [ ] GitHub 프로필에 선호하는 이름과 이미지 추가하기
-   [ ] Slack 가입하기
-   [ ] Slack 프로필에 선호하는 이름, 시간대, 이미지 추가하기
-   [ ] Slack의 `#new-contributors` 에서 자기소개하기
-   [ ] Slack의 `#support` 채널 가입하기
-   [ ] _선택사항_ StackOverflow 가입하기

3. 코드 기여 전

첫째, Wagtail에 기여하는 방법을 이해하기 전에 Wagtail로 구축하는 방법을 이해할 수 있는 것이 중요합니다. 아직 코드 기여 방법에 초점을 맞추지 말고, Wagtail을 사용하여 자신만의 기본 데모 웹사이트를 구축하는 방법에 초점을 맞춰 전체 Wagtail 시작하기 튜토리얼을 수행하는 데 시간을 투자하세요. 이를 위해서는 컴퓨터에 Python 및 기타 종속성이 설치되어 있어야 하며 처음에는 쉽지 않을 수 있지만, 계속 노력하고 막히면 질문하세요.

StackOverflow나 #support 에서 질문에 답하거나, 다른 패키지 중 하나 또는 Wagtail 사용자 가이드에 기여하는 등 다른 많은 기여 방법이 있다는 것을 기억하세요. 때로는 Wagtail의 코드나 CMS 인터페이스에 대한 감을 잡기 위해 코드 외 기여로 시작하는 것이 가장 좋습니다.

이슈 추적, 읽기 및 분류는 코드 기여의 중요한 부분이며 이슈 추적 가이드를 전체적으로 읽는 것이 좋습니다. 이를 통해 작업할 이슈를 찾고 이슈 분류로 팀을 지원하는 방법을 이해하는 데 도움이 됩니다.

참고

Take the time to read the issue and links before adding new comments or questions. Remember, it’s not time to ‘claim’ any issues yet either.

체크리스트

- [ ] Do the Wagtail tutorial
- [ ] Look at the Wagtail organization 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. 개발 환경 설정하기

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).

참고

Do not try to move past this step until you have a working bakerydemo code locally and a clone of the Wagtail repo that you can edit. When editing the Wagtail core code (both HTML and JavaScript) you should be able to refresh the site running locally and see the changes.

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.

참고

When developing, it’s recommended that you always read the latest version of the docs. Not the stable version. This is because it will better reflect what’s on the main code branch.

체크리스트

- [ ] 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

참고: Git과 GitHub 이해하기

git 은 버전 관리 도구로, 장치에 설치하여 일반적으로 명령줄(터미널)이나 일부 GUI 애플리케이션을 통해 실행합니다.

GitHub & GitLab은 git 을 사용하는 저장소를 위한 웹 사용자 인터페이스를 제공하는 두 개의 주요 웹사이트이며, Wagtail은 GitHub를 사용합니다.

Mozilla에는 Git과 GitHub를 설명하는 데 도움이 되는 훌륭한 가이드가 있습니다.

원격 저장소를 복제(clone)하는 방법과 그것이 실제로 무엇을 의미하는지:

  • On GitHub, you will not be allowed to directly create branches or changes in a repository (project) that you do not have access to.

  • 그러나 자신의 계정을 사용하여 이 저장소의 복사본(클론)을 만들 수 있으며, 이 클론에는 원래 저장소에 있던 모든 브랜치와 기록이 포함됩니다.

  • 이것은 때때로 ‘포크(fork)’라고도 불리며, 여러분의 저장소는 원래 저장소를 분기하는 자신만의 브랜치가 될 것입니다.

  • See the GitHub docs explain forking.

  • See Atlassian’s docs on git clone for more details.

5. 이슈 찾기

바라건대, 이 시점에서 프로젝트의 목적에 대해 잘 이해하고 여전히 기여하고 싶을 것입니다.

코드를 포크하고 로컬에서 실행한 후에는 무엇을 기여할지 찾아보기 시작하고 싶을 것입니다.

기여할 것을 찾는 것은 항상 쉽지 않으며, 특히 프로젝트에 새로 온 경우 더욱 그렇습니다. 조사할 몇 가지 후보 이슈가 있으면 전체 이슈 설명, 모든 댓글 및 모든 연결된 이슈 또는 풀 리퀘스트를 반드시 읽어보세요. 종종 다른 사람이 이슈를 시작했거나 완료했음을 발견할 수 있습니다. 때로는 문제에 접근하는 방법이나 문제가 해결할 가치가 있는지에 대한 설명이 댓글에 있기도 합니다.

이슈에 풀 리퀘스트가 연결되어 있고 아직 병합되지 않았다면 해당 풀 리퀘스트와 그에 대한 논의를 읽어보세요. 이전 기여자가 막혔거나 추진력을 잃었을 수 있으며, 이 경우 그들이 중단한 부분부터 이어서 할 수 있습니다(충분한 시간이 지났다고 가정). 문제 해결 방법에 대한 아이디어가 있다면 제안과 함께 댓글을 추가하세요. 우리 모두는 서로 돕는 것을 목표로 해야 합니다.

이슈에 good-first-issue 라벨이 붙어 있다면, 이는 보통 더 작고 처음 기여하는 사람들에게 좋다는 의미입니다. 기여할 다른 이슈를 찾는 데에는 문제가 없습니다. 주위를 둘러보고 무엇을 도울 수 있는지 확인해보세요.

마지막으로, ‘요청’하기 전에 다음을 수행할 수 있는지 확인하세요.

체크리스트 (후보 이슈용)

-   [ ] 누군가 활발히 작업하고 있지 않은지 확인하기 (지난 ~2개월간 최근 PR이나 댓글 없음)
-   [ ] 로컬 버전의 Wagtail에서 문제/시나리오를 재현할 수 있는지 확인하기
-   [ ] 해결책이 구현되었는지 검증하기 위해 단위 테스트를 작성할 자신감이 있는지 확인하기 (코드 변경인 경우)

6. 해결책 기여하기

중요: 이슈가 아무에게도 할당되지 않았고 이미 풀 리퀘스트가 없다면, 자유롭게 작업하세요. “이 이슈를 저에게 할당해주세요”라고 요청할 필요가 없습니다. 우리는 GitHub의 이슈 할당 기능을 Wagtail 핵심 팀 멤버에게 특정 이슈를 할당할 때만 사용합니다.

해결책을 기여할 준비가 되었다고 느끼면, 이제 중복된 노력을 방지하기 위해 그렇게 하려는 의도를 설명하는 댓글을 이슈에 추가하기에 좋은 시간입니다. “이 이슈를 저에게 할당해주세요”라고 요청하는 대신, 다음과 유사하게 작성하세요:

참고

이 문제/시나리오를 재현할 수 있었습니다. 이 작업을 계획하고 있으며, 제 대략적인 해결책은 (…설명)입니다.

단순히 문서 요청인 경우, 문서의 어느 부분에 섹션을 추가할 계획인지 설명하도록 이 댓글을 수정할 수 있습니다.

기여를 위한 새 브랜치 만들기

코드를 작성하기 전에, 잠시 git 모자를 쓰세요. 프로젝트를 로컬로 복제하면 main 브랜치에 체크아웃됩니다. 이 브랜치는 변경 사항을 적용하기에 적합하지 않습니다. 이 브랜치는 프로젝트의 핵심 개발을 추적하는 브랜치입니다.

대신, 잠시 시간을 내어 새 브랜치를 만드세요. 명령줄을 사용하거나 많은 훌륭한 git GUI 도구 중 하나를 설치할 수 있습니다. 명령줄을 사용하지 않으면 제대로 하고 있지 않다고 말하는 사람은 듣지 마세요. 오늘 배워야 할 것을 줄이고 나중에 git 명령줄 인터페이스에 집중하세요. Mac이 있다면 Fork를 추천하며, 그렇지 않으면 GitHub GUI도 충분히 좋습니다.

이 새 브랜치 이름은 수정 중인 내용에 대한 컨텍스트와 가능하면 수정 중인 이슈 번호를 포함해야 합니다. 예를 들어, git checkout -b 'feature/1234-add-unit-tests-for-inline-panel' 입니다. 이 브랜치 이름은 / 를 사용하여 폴더를 나타내고 이슈 번호 1234 도 포함하며, 마지막으로 이슈에 대한 짧은 설명과 함께 lower-kebab-case 를 사용합니다.

참고

You may find that your editor has some handy Git tooling and will often be able to tell you what branch you are on or whether you have any changes staged. For example, see VS Code’s support for Git.

변경 사항을 집중적으로 유지하기

개발자로서, 여기저기서 오타나 ‘옳지 않게’ 느껴지는 공백에 쉽게 주의가 산만해질 수 있습니다. 때로는 편집기조차도 다른 프로젝트의 구성으로 인해 동의 없이 파일을 저장할 때 파일 끝에 줄 바꿈을 추가하거나 코드를 서식 지정하는 등 주의가 산만해집니다.

주요 목표가 아니거나 프로젝트 설정에 의해 엄격하게 요구되지 않는 이러한 추가된 변경 사항은 노이즈입니다. 이 노이즈는 풀 리퀘스트를 검토하기 어렵게 만들고, 이러한 커밋을 보고 버그가 수정된 것과 어떻게 관련이 있는지 궁금해하는 미래의 개발자에게 혼란을 줄 수 있습니다.

변경 사항을 스테이징할 때, 필요한 부분만 스테이징하거나 최소한 변경 사항을 검토하고 커밋을 저장하기 전에 ‘되돌리세요’.

다른 문제(예: 문서의 오타)를 발견하면 이것이 브랜치가 있는 이유입니다. 커밋을 저장하고, main 에서 새 브랜치 fix/fix-documentation-typo 를 만들고, 해당 변경 사항을 해당 브랜치에 저장하세요. 이제 작고 병합하기 쉬운 변경 사항이 생겼으므로 풀 리퀘스트를 준비할 수 있습니다.

변경 사항을 목표에 집중하고, 필요하지 않은 것을 변경하여 검토자나 자신에게 오버헤드를 추가하지 마세요.

참고

It’s OK to make changes in a ‘messy’ way locally, with lots of commits that maybe include things that are not needed. However, be sure to take some time to review your commits and clean up anything that is not required before you do your pull request.

단위 테스트 작성하기

풀 리퀘스트를 만들기에 가까워졌지만, 다음 중요한 단계는 단위 테스트입니다. 작성한 코드에 대한 테스트를 추가하는 데 실제 버그 수정보다 5-10배 더 오래 걸리는 경우가 흔합니다. 종종, 사용 사례가 맞다면 문제를 해결하기 전에 테스트를 먼저 작성하고 실행(그러나 실패)시키는 것이 더 좋습니다.

새 프로젝트에서 단위 테스트를 작성하는 방법과 위치를 찾는 것은 어려울 수 있지만, 바라건대 프로젝트의 개발 문서에 시작하는 데 필요한 단서가 포함되어 있을 것입니다. 개발 문서의 전용 테스트 섹션을 읽어보세요.

버그를 수정하거나 새로운 기능을 도입하면, 그 수정이 오래 지속되고 다시 깨지지 않도록 하고 싶을 것입니다. 또한 엣지 케이스나 잠재적인 문제에 대해 생각함으로써 자신을 돕고 싶을 것입니다. 테스트는 이에 도움이 됩니다. 회귀는 발생하지만, 코드가 테스트될 때 발생할 가능성이 적습니다.

많은 프로젝트는 단위 테스트 없이 풀 리퀘스트를 검토조차 하지 않을 것입니다. 종종 버그를 수정하는 것은 어렵지 않고, 수정이 ‘진짜’ 수정인지 확인하고 다시 깨지지 않도록 하는 것이 어려운 부분입니다. 더 어려운 일을 하는 데 시간을 투자하세요. 개발자로서 성장하는 데 도움이 되고 기여가 더 오래 지속되는 차이를 만드는 데 도움이 될 것입니다.

참고

A pull request that just adds unit tests to some core functionality that does not yet have tests is a great way to contribute, it helps you learn about the code and makes the project more reliable.

체크리스트

- [ ] 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. 풀 리퀘스트(Pull Request) 제출하기

‘이슈 수정’이라는 제목의 풀 리퀘스트는 기껏해야 도움이 안 되고, 최악의 경우 스팸입니다. 잠시 시간을 내어 변경 사항에 제목을 어떻게 붙일지 생각해보세요. 해결된 문제나 추가된 기능 또는 수정된 버그를 (몇 단어로) 전달하세요. ‘10423 수정’ 대신, 단어를 사용하고 ‘문서 다크 모드 새로고침 이슈 수정’과 같은 제목을 작성하세요. 프로젝트의 누구도 이슈 10423 이 문서 다크 모드 새로고침 이슈에 대한 것인지 모릅니다.

풀 리퀘스트를 만들 때 적절한 제목을 추가하도록 노력해주세요. 이렇게 하면 팀에 나가는 모든 알림에 처음부터 적절한 제목이 포함되도록 할 수 있습니다.

참고

Remember you can make a draft pull request in both GitHub and GitLab. This is a way to run the CI steps but in a way that indicates you are not ready for a review yet.

풀 리퀘스트 설명 내에서 수정 중인 이슈를 참조하는 것은 좋은 제목만큼 중요합니다. 설명이 없는 풀 리퀘스트는 검토하기가 매우 어렵습니다. 설명 메시지에 fixes #1234 와 유사한 메모를 추가하면 GitHub에 해당 변경 사항이 해당 이슈에 대한 것임을 알릴 수 있습니다. 컨텍스트와 이슈 또는 시나리오를 재현하는 단계를 추가하세요.

변경 사항이 시각적인 경우 전후 스크린샷을 추가하는 것이 좋습니다. 이렇게 하면 변경 사항이 작동했는지 확인하는 데 도움이 되고 검토자가 변경 사항을 이해하는 데도 도움이 됩니다.

풀 리퀘스트에 대한 체크리스트를 직접 작성하고 빈칸을 채우는 것이 종종 좋습니다. 풀 리퀘스트 템플릿은 이유가 있으므로 해당 체크리스트도 사용해주세요.

풀 리퀘스트 체크리스트

-   [ ] 해결책에 대한 한 문장의 간략한 설명.
-   [ ] 이 풀 리퀘스트가 병합될 경우 해결되어야 할 이슈 링크.
-   [ ] 질문이나 가정, 예를 들어 CSS 변경으로 IE11을 더 이상 지원하지 않는다고 가정했다면, 문서에 없다면 그 가정을 기록하세요.
-   [ ] 세부 정보 - 검토자가 풀 리퀘스트를 이해하는 데 도움이 되는 추가 세부 정보, 컨텍스트 또는 링크.
-   [ ] 스크린샷 - 변경 전후에 추가됨.
-   [ ] 브라우저 및 접근성 검사 완료 또는 미완료. 설명에 추가됨.

7a. CI 실패 검토 및 수정

Once you have created your pull request, there will often be a series of build/check/CI steps that run.

These steps are normally all required to pass before the pull request can be merged. CI is a broad term but usually, the testing and linting will run on the code you have proposed to change. Linting is a tricky one because sometimes the things that are flagged seem trivial, but they are important for code consistency. Re-read the development instructions and see how you can run the linting locally to avoid frustrating back & forth with small linting fixes.

Testing is a bit more complex. Maybe all the tests can be run locally or maybe the CI will run tests on multiple versions of a project or language. Do your best to run all the tests locally, but there may still be issues on the CI when you do. That is OK, and normally you can solve these issues one by one.

The most important thing is to not just ignore CI failures. Read through each error report and try to work out the problem and provide a fix. Ignoring these will likely lead to pull requests that do not get reviewed because they do not get the basics right.

참고

GitHub will not run the CI automatically for new contributors in some projects. This is an intentional security feature and a core contributor will need to approve your initial CI run.

7b. Push to the same branch with fixes and do not open a new pull request

Finally, after you have fixed the failing linting and tests locally, you will want to push those changes to your remote branch. You do not need to open a new pull request. This creates more noise and confusion. Instead, push your changes up to your branch, and the CI will run automatically on those changes.

You can add a comment if you want to the pull request that you have updated, but often this is not really needed.

Avoid opening multiple pull requests for the same fix. Doing that means all the comments and discussion from the previous pull request will get lost and reviewers will have trouble finding them.

8. 다음 단계

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 prioritize.

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.

Responding to a review

Almost every Pull Request (PR) (except for the most smallest changes) will have some form of feedback. This will usually come in the form of a review and a request for changes. At this point your PR will be flagged as ‘needs work’, ‘needs tests’ or in some cases ‘needs design decision’. Take the time to read all the feedback and try to resolve or respond to comments if you have questions.

경고

Avoid closing the PR only to create a new one, instead keep it open and push your changes/fixes to the same branch. Unless directed to make the PR smaller, keep the same one open and work through items one by one.

Once you feel that you have answered all the concerns, just add a comment (it does not need to be directed at the reviewer) that this is ready for another review.

Once merged in

Well done! It’s time to party! Thank you for taking the time to contribute to Wagtail and making the project better for thousands of users.

Common questions

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)

  1. The fix or feature you are working on

  2. Tests

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

  4. 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 behavior.

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:

How can I be assigned an issue to contribute to

We only use GitHub’s issue assignment feature for members of the Wagtail core team 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.