devicetype-library/CONTRIBUTING.md

Contributing

This library is maintained by and for the community of NetBox users. As such, the regular contribution of accurate and complete device type definitions is crucial to its success.

Writing Definition Files

Each NetBox device type definition exists as a single YAML file, arranged by manufacturer (vendor). Files are named by concatenating the definition's model name with a .yaml extension. For example:

vendors/Acme/BFR-1000.yaml
vendors/Acme/BFR-2000.yaml

When writing new definitions, there are some important guidelines to follow:

• Every unique model number requires a discrete definition file, even if the set of components is identical.
• Include only components which are fixed to the chassis. Optional modular components should be omitted from the definition. (Note that this does not exclude field-replaceable hardware that is expected to always be present, such as power supplies.)
• Name components exactly as they appear in the device's operating system (as opposed to the physical chassis label, if different).

Additionally, be sure to adhere to the following style guidance:

• Do not begin the file with three dashes (---); YAML directives are not supported.
• Use two spaces for indenting.
• Specify a device type's attributes before listing its components.
• Avoid encapsulating YAML values in quotes unless necessary to avoid a syntax error.

The Contribution Workflow

The process of submitting new definitions to the library is as follows:

1. Verify that the proposed definition does not duplicate or conflict with an existing definition. (If unsure, please raise an issue seeking clarification prior to submitting a PR.)
2. Fork the GitHub project and create a new branch to hold your proposed changes.
3. Introduce the new content exactly as it should appear once accepted.
4. Submit a pull request to merge your new branch into the master branch. Include a brief description of the changes introduced in the PR.
5. GitHub will automatically run tests against your PR to validate it. If the tests fail, make the necessary changes to your branch so that they pass (or rescind the PR until you are able to do so). Please note that PRs which do not pass validation will be closed.
6. A maintainer will review your PR and take one of three actions:
   • Accept and merge it
   • Request revisions
   • Close the PR citing a reason (e.g. failing validation or not applicable to the library)