Issue assignment process clarification #42926
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -82,27 +82,54 @@ The task list in this issue will be used to compare the documented CSS propertie | |||||||||||||||||
|
|
||||||||||||||||||
| ## Guidelines for working on an issue | ||||||||||||||||||
|
|
||||||||||||||||||
| Remember that if you take on an issue, the expectation is for the work to be completed in a timely manner. | ||||||||||||||||||
| If you are unable to progress work on a claimed issue, please add a comment to let us know. | ||||||||||||||||||
|
|
||||||||||||||||||
| These are the general steps for working on an issue: | ||||||||||||||||||
|
|
||||||||||||||||||
| 1. **Find an issue:** | ||||||||||||||||||
|
|
||||||||||||||||||
| If you're looking to contribute, search for issues with a [`good first issue`, `help wanted`](#set_other_labels) or [`p3`](#set_a_priority_label) label. Most repositories have issues with these labels. You are welcome to browse and pick an issue that is suitable for your skill set. Another useful place to look for issues to work on is the [MDN Contributors Task Board](https://github.com/orgs/mdn/projects/25). This project view lists open issues from multiple repositories. You can filter the list based on the topics (`Labels` column) you're interested in. See the description of some of the [labels](#set_other_labels) that get applied during the issue triage process. | ||||||||||||||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||||||||||||||
|
|
||||||||||||||||||
| > [!NOTE] | ||||||||||||||||||
| > An issue with the `needs triage` label indicates that the MDN Web Docs core team has not reviewed the issue yet, and you shouldn't begin work on it. | ||||||||||||||||||
|
|
||||||||||||||||||
| 2. **Check that no one is already working on the issue:** | ||||||||||||||||||
|
Collaborator
Author
There was a problem hiding this comment. @dipikabh Thanks. I took some of your suggestions directly. But to properly fix the ordering and merging I had to start from scratch (rather than accepting your suggestions), so can you please have another look. I also formatted the bold parts of each point on their own line, which makes the steps much more readable.
Contributor
There was a problem hiding this comment. The formatting is looking great, agree, it's more readable and scanable now. |
||||||||||||||||||
|
|
||||||||||||||||||
| Before starting work on an issue, first check that no one is assigned to the issue (the _Assignees_ field is "Unassigned"). | ||||||||||||||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||||||||||||||
|
|
||||||||||||||||||
| Then check that there are no linked [Pull Requests](/en-US/docs/MDN/Community/Pull_requests), as these may indicate that another user has claimed the issue and started working on it. | ||||||||||||||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||||||||||||||
|
|
||||||||||||||||||
| 3. **Do the research:** | ||||||||||||||||||
|
|
||||||||||||||||||
| Most issues need some investigation before work can start. | ||||||||||||||||||
| - Scope out the work that needs to be done. | ||||||||||||||||||
| If the issue is not well-described, and/or you are not sure what is needed, feel free to @mention the poster and ask for more information. | ||||||||||||||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||||||||||||||
| - You can also ask for advice in the [MDN Web Docs chat rooms](/en-US/docs/MDN/Community/Communication_channels#chat_rooms). | ||||||||||||||||||
|
|
||||||||||||||||||
| 4. **Claim the issue:** | ||||||||||||||||||
|
|
||||||||||||||||||
| Contributors can "claim" unassigned and unclaimed issues by starting to work on them. | ||||||||||||||||||
|
|
||||||||||||||||||
| The steps are: | ||||||||||||||||||
|
Comment on lines
+112
to
+114
Contributor
There was a problem hiding this comment. "starting work" might feel vague. We should be explicit that claiming happens when a PR is linked to it
Suggested change
OR
Suggested change
|
||||||||||||||||||
| 1. Fork and branch the repository. | ||||||||||||||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||||||||||||||
| 2. Fix the issue and then open a [Pull Request (PR)](/en-US/docs/MDN/Community/Pull_requests) in the repository. | ||||||||||||||||||
| 3. In the PR description include the text `Fixes #<issue_number>` (if the PR only partially fixes the issue add the text `Related to #<issue_number>`). | ||||||||||||||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||||||||||||||
|
|
||||||||||||||||||
| Depending on the files you've updated in the pull request, a reviewer will be assigned to your pull request automatically. (Teams per topic area are defined in the [CODEOWNERS](https://github.com/mdn/content/blob/main/.github/CODEOWNERS) file). | ||||||||||||||||||
|
|
||||||||||||||||||
| If you have the necessary permissions, you should also _explicitly_ [assign the issue to yourself](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/assigning-issues-and-pull-requests-to-other-github-users#assigning-an-individual-issue-or-pull-request). | ||||||||||||||||||
|
|
||||||||||||||||||
| > [!NOTE] | ||||||||||||||||||
|
Contributor
There was a problem hiding this comment. what do you think about moving this note to right after the para that introduces
Contributor
There was a problem hiding this comment. On second thought, do we need this info as a note? Since it explains what I would also suggest turning this sentence into a note: "If you have the necessary permissions, you should also explicitly [assign the issue to yourself...." and placing it right after the explanation for |
||||||||||||||||||
| > Adding the `Fixes #<issue_number>` or `Related to #<issue_number>` text is what creates a cross-reference between the issue and the PR, and implicitly claims the issue for the PR's author. | ||||||||||||||||||
|
Contributor
There was a problem hiding this comment. since we've been addressing the contributor, suggesting a change of voice here:
Suggested change
|
||||||||||||||||||
| > If the work is going to take some time, you might want to create a draft PR to claim the issue before all work is complete. | ||||||||||||||||||
|
Contributor
There was a problem hiding this comment. Not sure if we should mention draft PRs. Folks who know about the option will likely use it judiciously. I'm slightly concerned that documenting it here could encourage folks to "claim" issues early/quickly. If we do keep it though, we could link to https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#converting-a-pull-request-to-a-draft |
||||||||||||||||||
|
|
||||||||||||||||||
| > [!WARNING] | ||||||||||||||||||
| > After opening the pull request, if you find you no longer have the time to make changes or incorporate review feedback, let the team know as soon as possible in a comment in the pull request. This will help the team assign another interested contributor to complete the work on the pull request and close the linked issue. | ||||||||||||||||||
|
|
||||||||||||||||||
| 5. **Close the issue:** | ||||||||||||||||||
|
Contributor
There was a problem hiding this comment. should probably be "Mark the issue as completed" |
||||||||||||||||||
|
|
||||||||||||||||||
| If you opened the pull request with `Fixes #<issue>` in the description, the issue should automatically be closed when the PR is merged! Otherwise you can manually close the issue. | ||||||||||||||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||||||||||||||
|
|
||||||||||||||||||
| ### Fixing issues yourself | ||||||||||||||||||
|
|
||||||||||||||||||
|
|
||||||||||||||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice! I like how you've worked "claimed" into the wording here. Also good point to remove "unassign" 👍
I don't think we use "us" for the core team...we could maybe say "add a comment so maintainers are aware and the issue can be picked up by another contributor."