mirror of https://github.com/zulip/zulip.git
146 lines
7.1 KiB
Markdown
146 lines
7.1 KiB
Markdown
# 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.](#find-work-to-be-completed)
|
|
1. [Review existing work and feedback.](#review-existing-work-and-feedback)
|
|
1. [Decide how to use prior work.](#decide-how-to-use-prior-work)
|
|
1. [Credit prior work in your commit history.](#credit-prior-work-in-your-commit-history)
|
|
1. [Present your pull request.](#present-your-pull-request)
|
|
|
|
## Find work to be completed
|
|
|
|
In Zulip's server and web app [repository](https://github.com/zulip/zulip), pull
|
|
requests that have significant work towards something valuable are often tagged
|
|
with a [completion candidate][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.
|
|
1. Rebase it on the current version of the `main` branch.
|
|
1. Carefully address any open feedback from reviewers.
|
|
1. Make any other changes you think are needed, including completing any parts
|
|
of the work that had not been finished.
|
|
1. Make sure the work of others is [properly credited](#credit-prior-work-in-your-commit-history).
|
|
1. [Self-review](../contributing/code-reviewing.md), test, and revise the work,
|
|
including potentially [splitting out](../contributing/commit-discipline.md)
|
|
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.
|
|
1. 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][coauthor-git-guide] 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](../contributing/commit-discipline.md).
|
|
|
|
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](../contributing/reviewable-prs.md) 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](#credit-prior-work-in-your-commit-history)
|
|
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.
|
|
|
|
[completion-candidate]: https://github.com/zulip/zulip/pulls?q=is%3Aopen+is%3Apr+label%3A%22completion+candidate%22
|
|
[coauthor-git-guide]: https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors
|