Get around GitHub

Tech doc writers (TW) are responsible for the docs. We write and edit the docs and exchange peer edits, maintain our backlog, and hero. To make it all happen, we use our Docs Team GitHub board to manage filed issues and pull requests (PRs).

The who's who of an issue or PR

GitHub tracks every stage of an issue or pull request's life cycle, including the people moving things along.

Because the Docs team invite anyone to file an issue or create a pull request through GitHub, we strongly recommend verifying a filer's relationship to the New Relic GitHub organization. If you're uncertain if a contributor is a Relic, a good trick is to check if they're a member of the New Relic GitHub org. Generally, we recommend assuming a filer is external until proven otherwise.

• Creator: This is the person who opens the issue or PR. The creator could be someone on the Docs team, another Relic, or an external user. You'll label the issue or PR differently depending on who created it.
• Assignee: This is the person who takes responsibility for an issue or PR and sees it through to publication. The Hero will assign non-TW issues and PRs to themselves, or they can take over an issue or PR from another writer.
• Reviewer: This is the person who provides a peer edit of your code or document and then approves the changes. This is not necessarily the person responsible for that area or responsible for merging the commit. You can assign up to 100 reviewers to a given issue.

Track issues in the board

The docs board has the following columns:

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 check everything in the Needs triage column. Drag cards from that column to the appropriate column.

Everyone on the team helps keep things moving:

• All writers should keep an eye on the Needs review column. If a PR doesn't have a reviewer, you can pick it up.
• When you are ready for any type of review (simple or complex), move your PR into Needs review.
• Be sure to move PRs that are blocked by SMEs to Waiting on SME/Blocked.
• Check Waiting on TW to merge to see if your PR feedback is finished.
• After you incorporate peer feedback, merge the PR, and remove it 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 #help-documentation channel and hero.

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

The Hero currently merges 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.

It's important to create a new release branch off of the develop branch. Before you create a new branch, make sure you're on develop.

To start a release:

1. Create a branch of develop using Github Desktop by clicking Current Branch in the top header, New Branch in the dropdown, then selecting Develop.
2. Name the branch with this pattern: daily-release/mm-dd-yy-morning/noon/evening. For example, a daily release happening at 9am on October 27, 2021 would follow this style: daily-release/10-27-21-morning.
3. To push your changes, in GitHub Desktop click Push Origin.
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. Only admins can delete them.

GitHub labels

We apply labels to issues so we can better triage and track the health of our backlog:

• content: All issues use this label. content indicates the issue is content-related rather than a design or engineering issue.
• pg_*: Docs team will always use this label to indicate 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 non-Relic opened the issue in the repo OR the issue 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

There's no hard and fast rule in choosing good candidates for docs issues. They could be anything too difficult for a docs hero to chase down, or anything that could benefit from deep engineering expertise. Some examples are code examples, requirements sections, and NRQL queries.

Ultimately, docs issues helps the docs team collaborate with product teams to solve documentation and product issues. It lets us leverage product team expertise to solve as many issues as we can, regarldess of who filed them.

The life cycle of a viable issues candidate looks something like this:

1. Someone files an issue through GitHub for the GitHub hero to evaluate it as a potential candidate.
2. The hero adds the docs-issue-candidate label. After, the hero archives the issue.
3. Every week, a designated docs team member assesses all issues with the docs-issue-candidate label.
4. If approved, the docs-issue-candidate label is changed to a docs-issue label. We then migrate the issue into the customer feedback Jira project.
5. The new jiras are triaged by PMs, then funneled to the correct project team.
6. The PM will give the ticket to an assignee, who will close it once complete.

Verify your commits

Setting up verified commits adds a little security to our process. This ensures that a commit came from your machine and not someone else remotely pretending to commit as you. When someone's commits are verified you'll see a label next to them.

First we'll need to install something called GPG. You can do this with homebrew:

brew install gpg

Once that's installed you can use it to create a key by running this command:

gpg --full-generate-key

This will trigger a series of prompts which you can answer like so:

• Your selection? 1
• What keysize do you want? (3072) 4096
• Key is valid for? (0) 0
• Key does not expire at all
  Is this correct? (y/N) y

You'll also be asked for your name and email address (the one you use with github) as well as a "comment". You can leave the comment blank and hit enter.

Here's an example of the full output:

reli ~ gpg --full-generate-key
gpg (GnuPG) 2.4.3; Copyright (C) 2023 g10 Code GmbH
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

gpg: directory '/Users/reli/.gnupg' created
Please select what kind of key you want:
   (1) RSA and RSA
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
   (9) ECC (sign and encrypt) *default*
  (10) ECC (sign only)
  (14) Existing key from card
Your selection? 1
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (3072) 4096
Requested keysize is 4096 bits
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) 0
Key does not expire at all
Is this correct? (y/N) y

GnuPG needs to construct a user ID to identify your key.

Real name: Reli Relic
Email address: rrelic@newrelic.com
Comment: 
You selected this USER-ID:
    "Reli Relic <rrelic@newrelic.com>"

You should then be prompted to create a password (twice). Make sure to save this somewhere! You'll see some output which you can ignore. Now you can run this command to see your key:

gpg --list-secret-keys --keyid-format LONG

Which will return something like this:

reli ~ % gpg --list-secret-keys --keyid-format LONG
gpg: checking the trustdb
gpg: marginals needed: 3  completes needed: 1  trust model: pgp
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
[keyboxd]
---------
sec   rsa4096/YOUR_KEY_ID 2023-07-18 [SC]
     ABC123ABC123ABC123ABC123ABC123ABC123
uid                 [ultimate] Reli Relic <rrelic@newrelic.com>
ssb   rsa4096/ABC123ABC123 2023-07-18 [E]

Now you can copy the value you see replaced by YOUR_KEY_ID in the above example. It might be a good idea to paste this somewhere temporarily since you'll be coming back to use it a few times.

Run this command and paste in your value in place of YOUR_KEY_ID

gpg --armor --export YOUR_KEY_ID | pbcopy

You won't see an output but it will have been copied to your clipboard. In github you'll navigate to your profile -> settings -> SSH and GPG keys. Here you can click "New GPG key", name it whatever you'd like, and paste in the previous block. It should look something like this:

-----BEGIN PGP PUBLIC KEY BLOCK-----

numbersandletters378468734658734somanynumbers83475837485
numbersandletters378468734658734somanynumbers83475837485
numbersandletters378468734658734somanynumbers83475837485
numbersandletters378468734658734somanynumbers83475837485
numbersandletters378468734658734somanynumbers83475837485
numbersandletters378468734658734somanynumbers83475837485
numbersandletters378468734658734somanynumbers83475837485

-----END PGP PUBLIC KEY BLOCK-----

Hit save and you're done in github.

Now we'll adjust some settings in git by running these commands with YOUR_KEY_ID being replaced by your key from earlier:

git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgsign true

Next we run this command to save additional information to your bash or zsh profile. If using zsh run:

if [ -r ~/.zshrc ]; then echo -e '\nexport GPG_TTY=\$(tty)' >> ~/.zshrc; \
else echo -e '\nexport GPG_TTY=\$(tty)' >> ~/.zprofile; fi

if using bash run:

if [ -r ~/.bash_profile ]; then echo -e '\nexport GPG_TTY=\$(tty)' >> ~/.bash_profile; \
else echo -e '\nexport GPG_TTY=\$(tty)' >> ~/.profile; fi

Now you can run a test to see how things are working. You'll probably need to enter the password you created with gpg earlier.

echo "test" | gpg --clearsign

If things aren't working, try running the following commands.

Run this command first to kill the gpg client:

gpgconf --kill all
gpg-agent --daemon

Then run echo test command again.

If it's still giving you an error, you may need to prompt it to use your variable and re-authenticate your password:

export GPG_TTY=`tty`

Then run this test again:

echo "test" | gpg --clearsign

Finally, try out a commit! If you use github desktop it's probably a good idea to quit/restart the app before committing. If an error occurs reach out to #doc_eng_help.