• /
  • Log in
  • Free account

Get around GitHub

As tech doc writers (TW) we edit docs, do peer edits, or use the Docs Team GitHub board to track the status of issues and pull requests (PR).

Who is who in an issue/PR?

GitHub keeps track of all activity concerning an issue or PR, including, of course, the people involved. When a new issue or PR is filed, check on the filer’s username and see if they're listed as a member of the New Relic organization. If they aren't, try to find them on Slack based on their username. If you're not sure about someone's affiliation, treat them as external until you know otherwise.

People in an issue/PR include:

  • Creator: The person who opened the issue or PR. This could be a writer, a Relic, or an external user. We'll label the issue or PR differently depending on who created it. If you're not sure if a user is a Relic, a good trick is to click on their profile and see if they're a member of the New Relic GitHub org.
  • Assignee: The person taking responsibility for a PR or issue. This will usually be used by the Hero or Sidekick to assign non-TW PRs and issues to themselves. It can also be used to take a TW’s PR or issue over from them.
  • Reviewer: The person who reviews or peer edits the code/document and approves the changes. Not necessarily the person responsible for that area or responsible for merging the commit. You can pre-assign up to 100 reviewers to a given issue.

Track issues in the board

The docs board has the following columns:

Column

Description

Needs triage

The Hero or Sidekick review and label issues and PRs in this column, then drag them to the appropriate column.

If a PR or issue is labeled eng, the Hero/Sidekick can go ahead and click its ellipses icon to archive it.

Hero: to do

PRs that the Hero needs to review, publish, and follow up with SMEs as needed.

Hero: Assign yourself as Assignee.

In review (Hero or any TW)

Drag PRs to this column when they are being reviewed. This shows who is reviewing and what is being reviewed, so two writers don’t mistakenly work on the same PR.

Any TW: Writer needs PR review

PRs from Tech Docs team members that need a light edit pass to make sure everything in GitHub is correct. This should be checked by other writers every few hours so PRs don’t get stale.

If you have a PR that’s been lingering here too long, ask for a reviewer in #doc_sprint_talk.

Whoever takes it: assign yourself as Reviewer.

Any TW: needs peer edit

Like our Needs Peer Edit column in Jira: A writer has requested a review of their PR. Review their PR in GitHub and leave comments.

Whoever takes it: assign yourself as Reviewer.

Waiting on SME/Blocked

For PRs that are blocked by need for SME info or confirmation (for example, as Hero you are waiting on an answer from the person who sent in a Hero pull request).

Waiting on TW to merge

All reviews are complete. The TW who created the PR (or who is assigned the issue) needs to merge this work into develop.

Drafts

A draft is a way to open a PR while indicating that the work is still in progress and not necessarily ready to merge immediately. You can't merge a Draft PR directly. Instead, you must move it out of draft status first.

When you see a draft PR (especially from outside the team!), treat it as though it's a working draft, and reach out to the creator to discuss.

Read more on GitHub's drafts.

As a Hero, make sure you attend to the following throughout your day:

  • Check in with the previous Hero at the start of your day (especially on Monday at the start of the week). Don’t forget to sync with the BCN Hero if necessary.
  • Watch for incoming PRs in #docs_deploys, and review everything in the Needs triage column. Drag cards from that column to the appropriate column.
  • Work through the cards in the Hero: to do column.

Everyone on the team helps keep things moving:

  • All writers should keep an eye on both Any TW columns.
  • There's one column for PRs that need a simpler review before merging (typo fixes, drive-by edits, etc), and another column for PRs that need a peer edit.
  • There are also two blocked columns: One for PRs blocked on a SME, and another column where we're waiting on the TW who created the PR to review feedback and/or merge.
  • After merging, remove your ticket from the board.

Deal with references in GitHub (and the style guide)

  • Don't link to anything non-public from a public place.
  • You can reference Jira tickets, but reference tickets by issue key (DOC-1234 is ok) rather than a link (https://newrelic.atlassian.net/browse/DOC-1234 is not).
  • Don't mention traffic or usage numbers publicly.
  • Don't reference internal people by name. If they have a GH account, @mention their GH handle. If they don't, talk instead about teams ("talk to a browser team engineer" or "Support Engineer") rather than people.
  • You can mention the #documentation channel and hero.

Merge releases into main work (or, when do we publish?)

The Hero currently merges three times a day: At 9 AM (morning), 12 PM (noon), and 3 PM (evening) Pacific. We merge release branches into main to avoid interuptions when someone merges into develop during a release. To learn more about this workflow, see the gitflow documentation in Atlassian.

To start a release:

  1. Create a branch based off develop Github Desktop by clicking Current Branch in the top header, clicking New Branch in the dropdown, and then selecting Develop.
  2. Name the branch following this pattern: daily-release/mm-dd-yy-morning/noon/evening. Here's an example: daily-release/10-27-21-morning.
  3. Push your changes by clicking Push Origin in GitHub Desktop.
  4. Create a pull request into main from your new daily release branch by clicking Create Pull Request. This will open a pull request screen on github.com. Pull requests default to merging into develop, so select main as the base branch in the left side of the page and then click Submit Pull Request.
  5. Wait until all the checks complete, and then merge the pull request.

All branches that follow the daily-release/mm-dd-yy-morning pattern are protected branches. This means the branches can't be deleted or pushed to by non-admins.

GitHub labels

Every issue needs labels to help us triage and track the health of our backlog:

  • content: Always add, this indicates the issue is content-related rather than a design or engineering issue.
  • pg_*: Always add to indicate the product group. For full definitions, see the "Doc Jira and GitHub fields" doc in the internal team Google Drive.
  • Indicate who created the issue:
    • from_internal: A Relic created it.
    • from_external: A user opened it in the repo OR it came in through #customer-feedback process.
    • from_tw: One of us created it (unless we were passing along #customer-feedback).
  • Optionally:
    • docs-issue-candidate: Issues that are too large in scope for the docs team to handle without product team expertise. This label alerts the docs issues team to migrate these issues into the customer feedback channel where they will be triaged and sent to product teams.
    • Jira’d: Issues that have a corresponding Jira ticket. Make sure you leave the Jira number in the comments of the issue (for example, DOC-1234).

Every pull request needs these labels so we can see where our contributions come from:

  • content: Always add, this indicates the PR is content-related rather than design or engineering.
  • Indicate who created the pull request:
    • from_internal: A Relic created it.
    • from_external: A user opened it in the repo OR it came in through #customer-feedback process.
    • from_tw: One of us created it (unless we were passing along #customer-feedback). If the PR fixes an external issue, label it as from_tw since the work was done by a tech writer.

Docs issues

Docs issues is a docs team program that enlists the help of product teams in solving documentation and product issues. The goal is to get product team expertise in solving issues filed by other relics and our users. Docs issues candidates are issues that would be difficult for a docs hero to chase down or would benefit from deep engineering expertise. Examples of good candidates are code examples, requirements sections, and NRQL queries.

The workflow for a viable issue looks something like this:

  1. A user files an GitHub issue and the GitHub hero identifies it as a potential docs issue.
  2. The hero marks the issue with the docs-issue-candidate label.
  3. Once a week, a designated docs team member goes through and assesses all issues with the docs-issue-candidate label.
  4. All approved issues get marked as docs-issue and migrated to the customer feedback Jira project.
  5. The new jiras are eventually triaged by PMs and funneled to the correct project team.
  6. The assignee works on the jira/issue and closes them once complete.
Create issueEdit page
Copyright © 2022 New Relic Inc.