Create a Github account if you don't already have one.
Fork this this repository.
Make your changes.
Test your changes! Review the project's READ ME for instructions on how to build and run tests locally.
Submit a Pull Request to this project with your changes.
If/when your PR is accepted, the automation in this project will build the site and deploy a new version of the code to developer.newrelic.com.
And you are done!

Submitting a PR from a cloned repo

Create a Github account if you don't already have one.
Clone this repository.
Create a new branch locally.
Make your changes.
Test your changes! Review the project's READ ME for instructions on how to build and run tests locally.
Submit a Pull Request to this project with your changes.
If/when your PR is accepted, the automation in this project will build the site and deploy a new version of the code to developer.newrelic.com.
And you are done!

Using the `develop` branch

Use the develop branch when creating your working branch locally. develop will always contain the most current source code. The develop branch will be merged into the main branch by the maintainers when a new release is ready to ship.

All pull requests should be made against the develop branch.

Branch Protection

The develop and main branches have "Branch Protection" enabled in Github. In order to merge a pull request into develop, you must have (at least) one approval. Additionally a few of the "PR Checks" are required and must pass before the pull request can be merged in.

You can review full Branch Protection details here, and check out a visual representation of the workflow below:

Using Conventional Commits

Please help the maintainers by leveraging the following conventional commit standards in your pull request title and commit messages.

Use `chore`

for minor changes / additions / corrections to content.
for minor changes / additions / corrections to images.
for minor non-functional changes / additions to github actions, github templates, package or config updates, etc

git commit -m "chore: adjusting config and content"

Use `fix`

for minor functional corrections to code.

git commit -m "fix: typo and prop error in the code of conduct"

Use `feat`

for major functional changes or additions to code.

git commit -m "feat(media): creating a video landing page"

Draft PRs

Draft PRs are ideal for in progress work or work you need others to contribute to.

To submit a Draft PR:

Make your code changes and submit a Pull Request.
Select Create a draft pull request on the PR submission screen on Github. You can find this by clicking on the Create pull request button at the bottom of the PR you wish to submit.
Once you are ready to have the PR reviewed and merge, click the Ready for review button on the PR.

Deploy previews with Gatsby Cloud

PRs that are opened from a branch in this repo (not forks) will generate preview links on Gatsby Cloud automatically. Gatsby Cloud preview links can be found as comments on your pull request once they finish building. Progress can be monitored via the Gatsby Build Service job under the Checks section.

Style guide adherence

In order to drive consistency in our documentation New Relic has provided a detailed Style Guide for you to follow when making contributions. Refer to this guide prior to contributing. When making documentation contributions follow these guidelines.

Reusable components

In order to drive simplicity and ease of use New Relic has provided a set of reusable components you can leverage when creating documentation. Refer to our Component Guide for more information.

Technical reference contribution guidelines

Technical reference pages are detailed technical specifications of the New Relic platform and its components.

Editing existing pages

To edit an existing page you can view the page's source code by clicking on the Edit icon in the upper right corner of the site.
Follow the instructions above to Fork or Clone the repo and make your edits.
Follow the instructions above to submit a PR for your change.

Creating new pages

If you'd like to create an entirely new page of documentation file a Documentation Request
The Developer Experience Team will review the request to add a new documentation page.
If a new page is approved you may be asked to help write the page content.
If you are willing to assist in the process of creating a new page, then follow the instructions above to Fork or Clone the repo and make your edits.
Follow the instructions above to submit a PR for your change.

Deleting pages

If you feel a page needs to be deleted file a Documentation Request.
The Developer Experience Team will review the request to delete an existing documentation page.
If the deletion is approved, The Developer Experience Team will delete the page.

New Relic guides

The New Relic guides are detailed product how-tos that are case driven. The guides provide steps for developing custom solutions for New Relic. This can mean custom ways of collecting and querying data, enhancing open source applications, or building new applications to meet specific needs. It can also mean automating processes to reduce toil.

Purpose

The guides aim to help developers learn about New Relic programmability, and to solve problems. Some guides are short, focused on a single task, and other taking you through multiple tasks to complete an end-to-end process.

Guides should have actionable steps and enough information for a reader to follow along. Guides have roughly the following sections:

Introduction - describe what problem the guide will solve or what skill it will teach.
Video or screenshot - describe how to complete the steps, or show what the end result will be. The point is to provide a graphical representation.
Before you begin - list prerequisites and necessary technology setups.
Steps (repeat as needed):
- high-level step
- code example
- additional information or sub-steps to help clarify the step
Related information - provide links to any additional resources, examples, and reference docs

Tips for writing guides

Review the style guide prior to contributing.

Check for existing content

New Relic has a rich set of documentation on our products so it's important you check for what is already may exist prior to starting to create a guide. It's recommended you search the following resources before contributing.

docs.newrelic.com
developer.newrelic.com
discuss.newrelic.com
opensource.newrelic.com

Editing existing guides

To edit an existing guide you can view the guide's source code by clicking on the Edit icon in the upper right corner of the site.
Follow the instructions above to Fork or Clone the repo and make your edits.
Follow the instructions above to submit a PR for your change.

Creating new guides

If you'd like to create an entirely new guide file a Documentation Request
We will review the request to add a new guide.
If a new guide is approved you may be asked to help write the guide content.
If you are willing to assist in the process of creating a new guide, then follow the instructions above to Fork or Clone the repo and make your edits.
Follow the instructions above to submit a PR for your change.

Deleting guides

If you feel a guide needs to be deleted file a Documentation Request
The Developer Experience Team will review the request to delete an existing guide.
If the deletion is approved, The Developer Experience Team will delete the guide.

Related Pages

related-pages.json is used to populate the related resources component with dynamic links. This file automatically updated every 24 hours via a script that runs in a GitHub action

That GH action fetches results for all pages from Swiftype, updates, commits, and pushes that related-pages.json file.

You should never attempt to update this file manually.

Updating navigation

When a new guide is added or an existing guide path frontmatter slug is changed it is important that the site navigation is updated to reflect this change. To do so follow these steps.

Make your guide change and submit a PR.
Within that PR also make the navigation change.
In order to change navigation you will need to update the nav.yml file.
Given the side navigation file is JSON, be sure to close all [ ] and { } and use trailing , correctly.
Navigation displayName should always be sentence case.
Submit your PR and add the navigation label.

Example navigation change

In the example below a new navigation element has been added called New Nav Item.

EXISTING

[
  {
    "displayName": "Collect data",
    "url": "/collect-data",
    "children": [
      {
        "displayName": "Log with the Log API",
        "url": "/"
      },
      {
        "displayName": "OpenTelemetry Exporter",
        "url": "/"
      },
      {
        "displayName": "Extend New Relic agents",
        "url": "/"
      },
      {
        "displayName": "Create Flex integration",
        "url": "/"
      }
    ]
  }
]

UPDATED

[
  {
    "displayName": "Collect data",
    "url": "/collect-data",
    "children": [
      {
        "displayName": "Log with the Log API",
        "url": "/"
      },
      {
        "displayName": "OpenTelemetry Exporter",
        "url": "/"
      },
      {
        "displayName": "Extend New Relic agents",
        "url": "/"
      },
      {
        "displayName": "Create Flex Integration",
        "url": "/"
      },
      {
        "displayName": "New nav item",
        "url": "/new-route"
      }
    ]
  }
]

Split testing and running experiments

If you have access to Split.io as a New Relic employee you can execute a split test on the site to measure different scenarios if you are attempting to gather data to make a product decision or conduct an experiment.

To execute a split test you'll need to be comfortable with Split.io as well as be able to provide the different treatments (in code) of what you wish to test.

To understand how to use Split.io it's recommended to watch this Introduction video

Step 1

Decide what you want to test, what your hypothesis is and begin to define your experiment.

Why are you running the experiment, what is the goal?
How will you measure to see if you reached the goal?
What is your metrics for success?
How long will it take to get to results you want?

Step 2

Review the Split.io documentation for creating a split test and targeting users.

Step 3

Send event data to Split.io

Step 4

Measure results by setting up a metric

A good metric:

is meaningful
is directional
has significance
is fit for the test you are running

Step 5

Run the experiment and pick a winner!

Updating the SDK documentation bundle

Periodically we need to update the NR1 SDK bundle that we use to generate our component documentation. In order to update the SDK, there are a few steps that need to happen:

Step 1: Update the release number in `gatsby-config`

We use a local Gatsby plugin gatsby-source-newrelic-sdk to source our documentation into GraphQL. This plugin has some configuration that tells it what release number to use.

Update gatsby-config.js with the new release number to update the bundle release version.

{
  "resolve": "gatsby-source-newrelic-sdk",
  "options": {
    "release": "release-3250"
  }
}

To obtain the version release number visit the one-core repository on Github enterprise and look at the release version in one-core/src/constants/sdk.js . You can use the one-core docs site to confirm if any issues are developer site specific or occurring in the SDK.

Step 2: Add any new APIs or components to our constants list

How to identify new components, APIs

At the moment, we don't have a rigorous or automatic process for identifying new components and APIs that we need to document. The goto manual process is to just eyeball the difference between the components we have on the site (or in constants.js), and what's displayed on the one-core site.

You can also check a file that resides in the wanda-ec-ui repository found in /src/__snapshots__/index.spec.js.snap that provides a visual check for SDK components and their levels of exposure.

It is possible to see a list of components from the SDK itself. If you run the site with the updated SDK version, you can enter Object.entries(window.__NR1_SDK__.default).map(array => array[0]) into the dev console in the browser for the running site. That will show you an array containing component and API names. You can use this to try and compare differences, but some manual investigation is still necessary, since the SDK also contains pre-release and internal-only components.

If a component looks like it should be internal only, feel free to ask #help-one-core to confirm if it should have public documentation, or if it is internal only.

Adding new components

We rely on the 1st party documentation bundle to power the developer docs. While the 1st party bundle provides many of the same components/APIs, there are a few minor differences between the 1st and 3rd party SDKs. To account for this, we white list the specific components we document on the site.
If there are any new components or APIs, update the constants list with the new components.
Pages will be then automatically generated for each of the new components.

Once we have a 3rd party bundle automatically built for us, we should no longer need this step as that will contain only 3rd party SDK documentation. That is an open request to the NR One Core Team.

Step 3: Add any new APIs or components to the navigation

If there are new APIs or components, we will want to list them in the navigation so that a user can easily discover them. Add an entry to nav.yml to get the new API/component in the nav.

Updating Developer terms

If you need to update the developer terms the following process can be used. These terms only change when requested by New Relic Legal, and they should not be modified unless requested by our legal team.

The Developers terms are found here

Obtain the approved file from Legal, usually in the form of a .docx type.
Use a tool such as Pandoc to convert the file to markdown.
Run this command to convert the file:

pandoc devterms.docx -o devterms.md

Start the process of updating the terms.

Developer terms in New Relic

The developer terms can be accepted in the New Relic platform in the Developer Center which is accessible when a user clicks on Build your own app.

The Developer Center functionality is located in an internal Github Enterprise repository: wanda/developer-center.
As long as the terms file doesn't incorporate custom components within the markdown (like JSX components that only exist within the developer-website repo) These internal terms will now automatically update when the terms source file changes.

Developer terms tips

It's very important all formatting stays the same as this is a legal document, so when making your changes look for the following issues that can occur when using Pandoc.

URL conversions - many times a URL will be formatted incorrectly.
Spacing or tab issues - can occur. Check the document is formatted correctly to align with legal standards.
Addition of / in place of commas or bolded text - when converting a document this issue will occur.
Formatting of bullets - sometimes bullets are formatted incorrectly.
Correct bolding of sub terms - sub terms sometimes are combined into a single paragraph.

Developer terms testing

Compare the original terms file to the changes you wish to make to look for issues and correct them as needed. Doing a split screen comparison can help you identify issues.
Review the terms on a preview branch after pushing your changes in a PR.
Have someone from the Legal team review the PR branch.

Files

CONTRIBUTING.md

Latest commit

History