Skip to content
This repository has been archived by the owner on Nov 28, 2023. It is now read-only.

Latest commit

 

History

History
303 lines (220 loc) · 12.6 KB

CONTRIBUTING.md

File metadata and controls

303 lines (220 loc) · 12.6 KB
Raw

Contributing

Welcome 👋

Contributions are always welcome. Before contributing please read the code of conduct and search the issue tracker; your issue may have already been discussed or fixed in main. To contribute, fork this repository, commit your changes, and send a Pull Request.

Note that our code of conduct applies to all platforms and venues related to this project; please follow it in all your interactions with the project and its participants.

Quickstarts style guide

Style tips

  • Maintain a strong active voice. Lead sentences with verbs.
    • Avoid “Allows you to monitor your uptime”
  • Avoid being too formal. Avoid words like thus and lastly, and feel free to use we and our.
  • In general, we should only lightly touch on what a given technology does. The user is already using Node, so we don’t need to sell them on it exactly. What we need to focus on is the challenges of monitoring that technology and then sell on that.

Check out our doc team's voice and tone guidelines.

Quickstarts usage

When writing about a quickstart the following language rules should be followed:

  1. Capitalize the term quickstart if the word is at the start of a sentence or header.

"Quickstarts are a great way to get started with New Relic!"

  1. If the term quickstarts is anywhere else in a sentence, use lower case.

"New Relic offers you a wide range of quickstarts to get you started."

  1. Quickstarts is always a single word.

"Always use quickstarts, not quick starts."

Quickstarts description template

  ## Why monitor <QUICKSTART_TECHNOLOGY>

  Explain the role and purpose of monitoring your technology. What are some specific difficulties about the technology? What are useful metrics to monitor?
  
  ### <QUICKSTART_TECHNOLOGY> quickstart highlights

  Describe the specific features of your quickstart. Mentions things such as dashboard visuals, alerts, and the type of instrumentation. We recommend the following format:

  Quick intro sentence:
  - First highlight
  - Second highlight
  - Third highlight

  ### New Relic + <QUICKSTART_TECHNOLOGY> (Optional)
  
  Describe how New Relic's capabilities can assist in monitoring your technology outside of what is included in the quickstart. Mention capabilies such as errors inbox, transaction traces, etc.

Quickstarts contributor guidelines

We encourage all contributors to actively engage in the creation and maintenance of quickstarts. Whether you work at New Relic or use New Relic as a customer, the community is open to your expertise!

  • Step 1: Review the quickstart Template Config for a definition of how to create a quickstart.
  • Step 2: Review the documentation for structure and limits you need to consider.
  • Step 3: Create your quickstart!
  • Step 4: Submit a PR!
  • Step 5: resolve feedback from code reviews.
  • Step 6: after approval, merge your PR.

When creating a new quickstart or reviewing a PR please keep the following in mind, and refer to the quickstart validation workflow for current validations.

Quick start best practices

Before getting started, review the documentation for quickstart structure and limits you need to consider.

You should also review the API limits for dashboards) and alerts to help you build your quickstart.

InstallPlans

See the docs for more details on installPlans.

  • The Ordering of installPlans is important as it sets the order of installation in the guided install flow for a user.
  • Every quick start that should be "installable" needs a documentation URL and an installPlan configuration if you want use the guided install flow.
  • You can view all the available installPlans in the Install directory.

Summary & descriptions

See the docs for more details on description and summary.

  • Use the proper YAML formatting | for URL description and summary.
  • Please review the YAML cheat sheet for more details.
  • Descriptions shouldn't have H1 # headers, and all H1 # headers will be rendered to H2 ## by default.
  • Use only 1 H2 ## as your top header.
  • Use H3 ### only throughout the rest of your description. As the markdown only supports up to H3 ###.
description: |
  a description of the quickstart.

summary: |
  a summary of the quickstart.

Documentation

See the docs for more details on documentation

  • The first documentation URL listed in the documentation configuration should be the primary doc reference.
  • The see installation docs buttons will always link to the primary documentation URL.
  • Every quick start that should be "installable" needs a documentation URL and an installPlan configuration if you want use the guided install flow.
  • Use the proper YAML formatting | for the URL description
  • Use the proper YAML formatting >- for documentation URL references.
  • Please review the YAML cheat sheet for more details.
documentation:
  - name: Name of documentation
    description: |
      Description of documentation
    url: >-
      https://docs.newrelic.com/docs/url/

Levels

See the docs for more details on levels

  • All quickstarts will be set to Community level by default unless specified differently by the Author.
  • Levels can only be modified by New Relic employees.
  • If you have questions on how to increase the level of support please file an issue
  • The shield icon is only applied to those quickstarts with Support Level New Relic OR Support Level Verified.

Dashboard images (screenshots)

See the docs for more details dashboards

  • Dashboard images are optional but highly recommended to preview the visual functionality of a dashboard.
  • file name should be quickstart_name01, quickstart_name02, etc
  • Dashboards images should be stored in the quickstart's dashboard directory. ex: /quickstart_name01/dashboards.
  • Must be in .png, .jpg, .jpeg or .svg format
  • Each image file must be less than 4MB in size
  • There should be no more than 6 dashboard images per dashboard
  • For best results use aspect ratio: 3:2
  • For best results use 800 px (width)
  • For best results use 1600 px (height)

Logos

See the docs for more details logos

  • Logo files should go in the root quickstart directory, /quickstarts_name01
  • Logos are optional but highly recommended to call attention to your quickstart.
  • .png or .jpeg or .svg format
  • Max 1
  • Aspect ratio: 1:1
  • 250px (width) x 100px (height)

Icons

See the docs for more details on icon

  • Icons are optional and not currently used in the UI.
  • .png or .jpeg or .svg format
  • Max 1

Keywords

See the docs for more details on keywords

When adding keywords to a quickstart the following format should be used. Keywords are used in UI navigation, filters and labels within the New Relic One I/O Catalog and the External I/O Catalog.

keywords:
  - a keyword
  - another keyword
  - yet another keyword

Keywords are strictly defined and you should provide a standard set of keywords in your quickstart from the list below. If you submit a keyword that is not defined in this list below, it will be reviewed for use after you submit a PR.

  • apm
  • automation
  • cms
  • containers
  • content management system
  • database
  • golang
  • infrastructure
  • java
  • kubernetes
  • language agent
  • load balancer
  • messaging
  • mobile
  • .net
  • networking
  • node.js
  • os
  • operating system
  • open source monitoring
  • php
  • python
  • queue
  • ruby
  • synthetics
  • testing
  • tracing
  • windows

Feature Requests

Feature requests should be submitted in the Issue tracker, with a description of the expected behavior & use case, where they’ll remain closed until sufficient interest, e.g. 👍 reactions, has been shown by the community. Before submitting an Issue, please search for similar ones in the closed issues.

Pull Requests

  1. Ensure that all new commits follow the Conventional Commit syntax.
  2. Provide a short description of the changes and screenshots of any visual changes.
  3. Ensure that all status checks are passing.
  4. You may merge the Pull Request in once you have the sign-off of one other developer, or if you do not have permission to do that, you may request the reviewer to merge it for you.

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"

Contributor License Agreement

Keep in mind that when you submit your Pull Request, you'll need to sign the CLA via the click-through using CLA-Assistant. If you'd like to execute our corporate CLA, or if you have any questions, please drop us an email at [email protected].

For more information about CLAs, please check out Alex Russell’s excellent post, “Why Do I Need to Sign This?”.

Slack

We host an internal help Slack channel. You can contact the teams supporting quickstarts and I/O with any questions here.

Partnerships

to be updated