zulip/docs/contributing/continuing-unfinished-work.md

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:

1. Find work to be completed.
2. Review existing work and feedback.
3. Decide how to use prior work.
4. Credit prior work in your commit history.
5. Present your pull request.

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:

1. Pull down the existing pull request.
2. Rebase it on the current version of the main branch.
3. Carefully address any open feedback from reviewers.
4. Make any other changes you think are needed, including completing any parts of the work that had not been finished.
5. Make sure the work of others is properly credited.
6. 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:

1. Make your own changes from scratch.
2. 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 with git 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.