• ログイン

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.

Who's who of an issue or PR:

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

Column

Description

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.

Hero to triage

This is the column where new PRs and GitHub issues land on the board. After inspecting and labeling them, the Hero drags them to the appropriate column.

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

Scheduled work

Use this column for "What's new" posts or other time-sensitive issues that you want the hero to watch. Insert the projected publication date in the title so everyone can see it.

In progress

Drag PRs to this column when you are working on them. Make sure your face is on the PRs so other writers don’t mistakenly work on them.

Needs review

This is where you insert your PRs when you are ready to get a review. This is for all types of reviews: everything from minor fixes to complicated Jiras.

  1. Make sure you insert comments about what kind of review you need in the body of the PR.
  2. Either ping a colleague for a review, or let a colleague pick it up at random.
  3. If you want a specific person to review the PR, add their name as a reviewer.
  4. If you have a PR that’s been lingering here too long, ask for a reviewer in #doc_sprint_talk.

In review

When you pick up a PR from Needs review:

  1. Make sure your name is listed as a reviewer.
  2. Move the PR into this column while you review it.
  3. Review the PR in GitHub and leave comments.
  4. When you are finished with the review, move it to Waiting on technical writer to merge.

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.

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.
Copyright © 2022 New Relic株式会社。

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.