The Docs pull requests and Issues board is our source of truth for what's going on in our project. The board is divided into a series of columns so we can see visually what the status of each issue and pull request is.
A note on Assignee vs Reviewer
Assignee and Reviewer have different meanings:
- Assignee means you own the pull request or issue and are getting it into a merge-ready state. If you are no longer owning a given pull request or issue, take your name off as assignee.
- Reviewer means you are actively reviewing a pull request. If it's a pull request from outside the docs team, the reviewer is also responsible for merging the pull request into
develop. If you're reviewing a pull request from a fellow docs writer, add your comments and mark the pull request as Approved, then move it to Waiting on TW to merge.
These issues and pull requests are in a draft state. Do not merge until their owner moves them out of the column. This column should only be for draft pull requests. Do not "hold" pull requests or issues here.
The Hero should look at this column multiple times per day in case a pull request has been marked ready for review. Move any ready-for-review pull requests into the correct column.
Hero to triage column
New issues and pull requests flow into this column automatically. As hero, you need to triage each one:
- Determine if the pull request or issue is content-related. If it's an eng issue or pull request, you can just Archive it to remove it from the board.
- Assign mandatory labels:
Label type Required on Description
Issues and pull requests Use this label to indicate an issue or pull request relates to content (versus the code of the site).
Issues and pull requests Use this label to indicate who created the issue or pull request. Use
from_twwhen it's created by a docs writer,
from_internalwhen it's created by a Relic, and
from_externalwhen it's from outside the company.
Issues Indicates which New Relic product group is associated with this issue.
- Give the ticket an assignee (most likely you).
- Move the ticket to the appropriate column.
Hero: To do column
Work that the GitHub has triaged, but hasn't started working on yet. Tickets in this column need to have an assignee.
In progress/being reviewed column
Work is underway on this issue or pull request. For example, reviewing pull requests from outside the team, doing a peer edit, investigating a GitHub issue. The person doing the work should make themselves the assignee as soon as they move the pull request or issue into this column to prevent others from duplicating work.
Writer needs PR review column
Exactly what it says. Typically, the writer who submitted the pull request will move it to this column.
A pull request review means reviewing for basic stuff like is it rendering correctly, are there typos or wording issues, and are there any obvious errors in the .mdx content shown in the diff. Once you've reviewed the pull request, mark it approved in the GitHub review UI, and move it to the Waiting on TW to merge column.
Writer needs peer edit column
Also exactly what it says. As with pull request review column, the writer who submitted the pull request will drag to this column.
This includes all the stuff in a pull request review plus an actual peer edit. Once you've reviewed the pull request and left your feedback in the GitHub review UI, mark it Approved and move it to the Waiting on TW to merge column. From there, the author of pull request is responsible for reviewing the feedback and updating it before merging. If you find significant issues (inaccuracies, bad formatting, build issues), don't mark it Approved.
Waiting on SME/blocked column
Blocked until something else happens. Usually this means it's waiting on answers or approval from the SME or the person who submitted the pull request.
Waiting on TW to merge column
When a docs writer creates a pull request, it's their responsibility to merge it into
develop at the appropriate time. After a reviewer is done with their pull request review or peer edit, they move it into this column so the original writer can merge when ready.
We welcome thoughts or questions on our handbook! The easiest way to get in touch is to file a GitHub issue.