Issue assignment process clarification #42926

hamishwillee · 2026-01-27T00:43:54Z

The Guidelines for working on an issue suggest that users self assign if they can, and otherwise add a comment asking to be assigned.

In theory this is good - user asks to be assigned, and a core user then assigns them. Historically though this often doesn't work - you get people asking to be assigned to multiple issues, then getting assigned and doing no work. The issues then rot.

The current and well established process is that authors start work and create the cross link Fixes #<issue no.> in the PR to implicitly assign the issue.

The weakness in the process is that there is a window where multiple users might attempt to take the issue, and it is a little harder to see who owns the issue.
The benefit is that it is clear that the assignee is actually working on the issue, and you can still assign as needed etc.

This updates the process to reflect how assignment is actually handled on MDN.

github-actions · 2026-01-27T00:45:23Z

Preview URLs (1 page)

/en-US/docs/MDN/Community/Issues

External URLs (2)

URL: /en-US/docs/MDN/Community/Issues
Title: Creating and working on issues

https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/assigning-issues-and-pull-requests-to-other-github-users (1 time) (Note! This may be a new URL 👀)
https://github.com/orgs/mdn/projects/25 (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2026-01-30 00:34:53)

chrisdavidmills

@hamishwillee looks good, man; a couple of suggestions, but nothing major.

Also, while you're here, consider:

Fixing the grammar issue in the first numbered bullet — "If you're looking to contribute, search for issues with" should be "If you're looking to contribute, search for issues with a"
Adding a warning about not submitting AI slop fixes, as they waste our time as we will probably close them? Hrm, maybe this one requires more discussion.

files/en-us/mdn/community/issues/index.md

caugner

LGTM from my point of view, I'll let others approve.

files/en-us/mdn/community/issues/index.md

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com> Co-authored-by: Claas Augner <495429+caugner@users.noreply.github.com>

hamishwillee · 2026-01-27T21:11:26Z

Thanks all for the review - I have accepted all suggestions and fixed the typo. Chris, yes, would be great to add a comment on AI slop as a separate PR.

dipikabh

Thanks for taking this on, Hamish! 🙌
I have a few rewording suggestions and a broader suggestion to adjust the step list to accommodate the current set of changes.

files/en-us/mdn/community/issues/index.md

chrisdavidmills

Looks good from my end.

hamishwillee · 2026-01-30T00:37:58Z

files/en-us/mdn/community/issues/index.md

   > 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. **Assign the issue to yourself:** After finding an issue you'd like to work on, make sure that the issue is not assigned to anybody else. Add a comment saying you would like to work on the issue, and if you are able to, [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).
+2. **Check that no one is already working on the issue:**


@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.

The formatting is looking great, agree, it's more readable and scanable now.

dipikabh

Great work! Approving.
I'll check in on Monday to see how it shapes up.

dipikabh · 2026-01-30T16:11:32Z

files/en-us/mdn/community/issues/index.md


-Remember that if you take on an issue, the expectation is for the work to be completed in a timely manner. If you're not able to make any progress for a week after being assigned or can no longer complete the required task, leave a comment and unassign yourself from the 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.


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."

dipikabh · 2026-01-30T16:30:49Z

files/en-us/mdn/community/issues/index.md

-1. **Find an issue:** If you're looking to contribute, search for issues with [`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.
+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.


accepting PR label will be added via https://github.com/mdn/content/pull/41035/changes L232

Realistically, we don't use priority labels while triaging but I'll let those changes trickle in via that PR.

Suggested change

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.

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 Contributor 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.

dipikabh · 2026-01-30T16:34:33Z

files/en-us/mdn/community/issues/index.md

-2. **Assign the issue to yourself:** After finding an issue you'd like to work on, make sure that the issue is not assigned to anybody else. Add a comment saying you would like to work on the issue, and if you are able to, [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).
+2. **Check that no one is already working on the issue:**
+
+   Before starting work on an issue, first check that no one is assigned to the issue (the _Assignees_ field is "Unassigned").


Suggested change

Before starting work on an issue, first check that no one is assigned to the issue (the _Assignees_ field is "Unassigned").

Before starting work on an issue, first check that no one is assigned to the issue (the _Assignees_ field should be "Unassigned").

dipikabh · 2026-01-30T16:35:35Z

files/en-us/mdn/community/issues/index.md

+
+   Before starting work on an issue, first check that no one is assigned to the issue (the _Assignees_ field is "Unassigned").
+
+   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.


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.

Then check that there are no linked [Pull Requests](/en-US/docs/MDN/Community/Pull_requests), as these may indicate that another contributor has claimed the issue and started working on it.

dipikabh · 2026-01-30T16:40:32Z

files/en-us/mdn/community/issues/index.md

+
+   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.


Suggested change

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.

If the issue is not well-described, and/or you are not sure what is needed, feel free to mention the person who opened the issue (using @username) and ask for more clarifying information.

dipikabh · 2026-01-30T17:13:52Z

files/en-us/mdn/community/issues/index.md

+   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]
+   > 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.


since we've been addressing the contributor, suggesting a change of voice here:

Suggested change

> 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.

> 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 marks the issue as claimed by you.

dipikabh · 2026-01-30T17:27:03Z

files/en-us/mdn/community/issues/index.md

+
+   > [!NOTE]
+   > 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.
+   > 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.


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

dipikabh · 2026-01-30T17:51:47Z

files/en-us/mdn/community/issues/index.md

+5. **Close the issue:**

-5. After your pull request has been reviewed and merged, you can mark the linked issue as closed. If you opened the pull request with `Fixes #<issue>` verbiage, the issue will be closed automatically when the pull request is merged.
+   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.


I actually prefer the previous phrasing with "will be"

Contributors might not have permissions to close an issue opened by someone else if they don't have triage permissions.

Suggested change

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.

If you opened the pull request with `Fixes #<issue>` in the description, the issue will be closed automatically when the PR is merged. Otherwise, you can add a comment to the issue linking to one or more pull requests that fix it, and a maintainer will close the issue as completed.

dipikabh · 2026-01-30T18:07:06Z

files/en-us/mdn/community/issues/index.md

   > 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. **Assign the issue to yourself:** After finding an issue you'd like to work on, make sure that the issue is not assigned to anybody else. Add a comment saying you would like to work on the issue, and if you are able to, [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).
+2. **Check that no one is already working on the issue:**


The formatting is looking great, agree, it's more readable and scanable now.

dipikabh · 2026-01-30T18:16:53Z

files/en-us/mdn/community/issues/index.md

+   > 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.

-   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:**


should probably be "Mark the issue as completed"

Issue assignment process clarification

72ed5b2

hamishwillee requested review from caugner and dipikabh January 27, 2026 00:43

hamishwillee requested a review from a team as a code owner January 27, 2026 00:43

github-actions bot added Content:Meta Content in the meta docs size/s [PR only] 6-50 LoC changed labels Jan 27, 2026

chrisdavidmills requested changes Jan 27, 2026

View reviewed changes

files/en-us/mdn/community/issues/index.md Outdated Show resolved Hide resolved

files/en-us/mdn/community/issues/index.md Outdated Show resolved Hide resolved

caugner reviewed Jan 27, 2026

View reviewed changes

files/en-us/mdn/community/issues/index.md Outdated Show resolved Hide resolved

hamishwillee and others added 2 commits January 28, 2026 08:07

Apply suggestions from code review

7713fa0

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com> Co-authored-by: Claas Augner <495429+caugner@users.noreply.github.com>

typo spotted by ChrisM

5ea8ae8

hamishwillee requested a review from chrisdavidmills January 27, 2026 21:10

dipikabh approved these changes Jan 28, 2026

View reviewed changes

chrisdavidmills approved these changes Jan 28, 2026

View reviewed changes

hamishwillee added 2 commits January 30, 2026 09:58

Apply suggestions from code review

8011f5d

Merge other bullets

d20103a

hamishwillee commented Jan 30, 2026

View reviewed changes

dipikabh approved these changes Jan 30, 2026

View reviewed changes

	Before starting work on an issue, first check that no one is assigned to the issue (the _Assignees_ field is "Unassigned").
	Before starting work on an issue, first check that no one is assigned to the issue (the _Assignees_ field should be "Unassigned").


		Before starting work on an issue, first check that no one is assigned to the issue (the _Assignees_ field is "Unassigned").

		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.

	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.
	If the issue is not well-described, and/or you are not sure what is needed, feel free to mention the person who opened the issue (using @username) and ask for more clarifying information.

	> 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.
	> 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 marks the issue as claimed by you.

	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.
	If you opened the pull request with `Fixes #<issue>` in the description, the issue will be closed automatically when the PR is merged. Otherwise, you can add a comment to the issue linking to one or more pull requests that fix it, and a maintainer will close the issue as completed.

Issue assignment process clarification #42926

Are you sure you want to change the base?

Issue assignment process clarification #42926

Uh oh!

Conversation

hamishwillee commented Jan 27, 2026

Uh oh!

github-actions bot commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chrisdavidmills left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

caugner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hamishwillee commented Jan 27, 2026

Uh oh!

dipikabh left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chrisdavidmills left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dipikabh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Jan 27, 2026 •

edited

Loading

chrisdavidmills left a comment •

edited

Loading