Continuing unfinished work
Sometimes, work is started on an issue or PR, but not brought to completion. This may happen for a variety of reasons — the contributor working on the project gets busy, maintainers cannot prioritize reviewing the work, a contributor doesn’t have the skills required to complete the project, there is an unexpected technical challenge or blocker, etc.
Completing work that someone else has started is a great way to contribute! Here are the steps required:
Find work to be completed
In Zulip’s server and web app repository, pull requests that have significant work towards something valuable are often tagged with a completion candidate label. You can review this label for unfinished work that you find interesting and have the skills to complete.
Note that it’s common to see one or more pull requests linked to an issue you’re interested in. The guidelines below apply regardless of whether you intentionally set out to find work to complete or simply find yourself building on someone else’s work.
Review existing work and feedback
Any time there are pull requests linked to the issue you are working on, start by reviewing the existing work. Read the code, and pay close attention to any feedback the pull request received. This will help you avoid any pitfalls other contributors encountered.
Decide how to use prior work
Consider how to use prior work on the issue. In your best judgment, is the existing PR on the right track? If there’s reviewer feedback, it should help you figure this out.
If prior work looks like a good start:
Pull down the existing pull request.
Rebase it on the current version of the
main
branch.Carefully address any open feedback from reviewers.
Make any other changes you think are needed, including completing any parts of the work that had not been finished.
Make sure the work of others is properly credited.
Self-review, test, and revise the work, including potentially splitting out preparatory commits to make it easier to read. You should be proud of the resulting series of commits, and be prepared to argue that it is the best work you can produce to complete the issue.
Otherwise, you can:
Make your own changes from scratch.
Go through reviewer feedback on prior work. Would any of it apply to the changes you’re proposing? Be sure to address it if so.
Credit prior work in your commit history
When you use or build upon someone else’s unmerged work, it is both professionally and ethically necessary to properly credit their contributions in the commit history of work that you submit. Git, used properly, does a good job of preserving the original authorship of commits.
However, it’s normal to find yourself making changes to commits
originally authored by other contributors, whether resolving merge
conflicts when doing git rebase
or fixing bugs to create an
atomically correct commit compliant with Zulip’s commit
guidelines.
When you do that, it’s your responsibility to ensure the resulting
commit series correctly credits the work of everyone who materially
contributed to it. The most direct way to credit the work of someone
beyond the commit’s author maintained in the Git metadata is
Co-authored-by:
line after a blank line at the end of your commit
message:
Co-authored-by: Greg Price <greg@zulip.com>
Be careful to type it precisely, because software parses these commit message records in generating statistics. You should add such a line in two scenarios:
If your own work was squashed into a commit originally authored by another contributor, add such a line crediting yourself.
If you used another contributor’s work in generating your own commit, add such a line crediting the other contributor(s).
Sometimes, you make a mistake when rebasing and accidentally squash
commits in a way that messes up Git’s authorship records. Often,
undoing the rebase change via git reflog
is the best way to correct
such mistakes, but there are two other Git commands that can be used
to correct Git’s primary authorship information after the fact:
git commit --amend --reset-author
will replace the Git commit metadata (date, author, etc.) of the currently checked out commit with yourself. This is useful to correct a commit that incorrectly shows someone else as the author of your work.git commit --amend -C <commit_id>
will replace the commit metadata (date, author, etc.) on a commit with that of the provided commit ID. This is useful if you accidentally made someone else’s commit show yourself as the author, or lost a useful commit message via accidental squashing. (You can usually find the right commit ID to use withgit reflog
or from GitHub).
As an aside, maintainers who modify commits before merging them are
credited via Git’s “Committer” records (visible with git show --pretty=fuller
, for example). As a result, they may not bother with
adding a separate Co-authored-by
record on commits that they revise
as part of merging a pull request.
Present your pull request
In addition to the usual guidance for putting together your pull request, there are a few key points to keep in mind.
Take responsibility for the work. Any time you propose changes to the Zulip project, you are accountable for those changes. Do your very best to verify that they are correct.
Don’t submit code you don’t understand — dig in to figure out what it’s doing, even if you didn’t write it. This is a great way to catch bugs and make improvements.
Test the work carefully, even if others have tested it before. There may be problems that the reviewers missed, or that were introduced by rebasing across other changes.
Give credit where credit is due. Reviewers should be able to examine your commit history and see that you have properly credited the work of others.
Explain the relationship between your PR and prior work in the description for your pull request.
If you started from an existing PR, explain what changes you made, and how you addressed each point of reviewer feedback that hadn’t been addressed previously.
If you started from scratch, explain why you decided to do so, and how your approach differs from prior work.