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:

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

• Check in with the Hero/Sidekick 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 from develop into main work (or, when do we publish?)

The Hero currently merges three times a day: At 9 AM, noon, and 3 PM Pacific.

• Slackbot will remind us about this in #docs_deploys.
• The hero (or delegate) is the one who should create a PR for this and merge it.

Github labels

Every issue needs these labels:

• Always add content
• Add one of the pg_* labels (see this internal doc )
• Add one of:
  • 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).
• Optional: 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:

• Always add content
• Add one of:
  • 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.
• Optional: Jira’d: Issues that have a corresponding Jira ticket. Make sure you leave the Jira number in the comments of the PR (for example, DOC-1234).

Check the edit history of a doc or file

There are a few options for checking the history of a file:

Option 1: Github history tab

1. Navigate to the doc on the doc site and click Edit page in the right nav.
2. Click History in the top right corner of the doc.
3. Bob's your uncle

Option 2: githistory.xy

1. Navigate to your specific file on Github.com:

   https://github.com/newrelic/docs-website/blob/develop/src/content/docs/browser/new-relic-browser/browser-agent-spa-api/add-page-action.mdx

   コピー

2. In the url, replace github.com with github.githistory.xyz:

   https://github.githistory.xyz/newrelic/docs-website/blob/develop/src/content/docs/browser/new-relic-browser/browser-agent-spa-api/add-page-action.mdx

   コピー

3. It will take you to a site which presents the visual history of that specific file. You can view changes by clicking through the commit history at the top of your page.

Option 3: Git blame

Follow Github's documentation.