Your first contribution, step by step #

This page walks you through a first contribution. Choose the path that fits what you found. All paths end in a pull request that is reviewed in public.

Contents #

1. Choose a small, real task
2. Path A: a documentation fix
3. Path B: a translation
4. Path C: a code fix
5. Writing the pull request
6. After you send it

Choose a small, real task #

Good first tasks, from Mentoring a first contribution:

• a typo or an outdated step in a help page you read;
• a missing link to a deeper page;
• a handful of strings in your language;
• a small bug you hit yourself, with a clear fix.

Avoid "practice" pull requests with no real change, and large tasks. The first one should be finished in an hour or two. Search the issue tracker first: if your problem is known, add what you know to that issue.

Path A: a documentation fix #

1. On the help page, press Edit on GitHub (Contributing documentation).
2. Change the text in the browser. Keep the style of the page: American English, "Exponential" for the product, a source for every fact.
3. Write a commit message such as Fixed: The languages help names the Apply button.
4. Propose the change and open the pull request.

The help pages are the files in doc/ of the kernel, so a documentation fix is a pull request to se7enxweb/exponential. More: Improving the help as a student.

Path B: a translation #

1. Check the language's completeness in doc/eng-us/languages.md.
2. Fork the repository and open share/translations/<locale>/translation.ts.
3. Translate untranslated or unfinished messages; keep placeholders such as %1 exactly.
4. Switch the administration to your language and look at the screens you translated.
5. Commit with a subject such as Updated: German translation of the help dashboard and open a pull request.

Source: Contributing translations. More: Translating as a student.

Path C: a code fix #

From Develop with Git, for an extension such as eztags (the kernel works the same way):

1. On GitHub, open the repository and press Fork.

2. Add your fork as a second remote and start a branch:

   cd extension/eztags
   git remote add fork https://github.com/<you>/eztags.git
   git switch -c fix-tag-search

3. Make the change, test it on your study site, and commit it:

   git commit -am "Fixed: The tag search finds tags with an apostrophe"
   git push -u fork fix-tag-search

4. Follow the link GitHub prints to open a pull request (or gh pr create).

For the kernel itself, read CONTRIBUTING.md first: run make hooks once, keep share/filelist.md5 current with make manifest-fix, and make sure your signed CLA is on file before the merge (The CLA for students).

Writing the pull request #

Title:    Fixed: <what the change does, in one line>

What:     <the problem, in two sentences>
Why:      <who it affects>
How I tested it:
          <release, PHP version, steps, what I saw before and after>
CLA:      <signed / not needed (documentation fix in an extension of my own, etc.)>

The kernel's pull request template has a checkbox for the CLA. Keep personal data, passwords and server details out of the description and the screenshots.

For a first contribution, pick a fix nobody can disagree with. If the behavior you want to change might be on purpose or open to interpretation, it may be a negative feature other sites depend on: such a change needs a strong "Why", is better offered as an option than a new default, and can take several rounds of review before it is merged.

After you send it #

• Expect review rounds. 7x reviews in many more rounds than usual; it "is not a judgment of you" (Contributors guidelines).
• Answer every comment in the pull request.
• Squash and rebase onto main when asked: git fetch origin, git rebase -i origin/main, git push --force-with-lease, only to your pull request branch.
• When it is merged, add it to your portfolio and your journal. Then pick the next task.

Related pages #

• Contributing as a student
• Using Git as a student
• Develop with Git
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.