Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
112 lines (78 loc) · 4.91 KB

CONTRIBUTING.md

File metadata and controls

112 lines (78 loc) · 4.91 KB

NetBox DHCP Contribution Guidelines

Thank you for taking the time to contribute to the NetBox DHCP project!

Issues

When you discover a problem with NetBox DHCP, search for an existing issue first. If there isn't a related issue, you can open a new one.

Include the following information in your post:

  • Use the issue template provided by GitHub when starting a new issue.
  • Specify your Python, NetBox and NetBox DHCP versions. If possible, check if this issue has been fixed in a later release.
  • Whenever possible, include a minimal reproducible example to help identify the problem.
  • Describe what actually happened. Include the full traceback if an exception occurred. If possible, set the NetBox Django environment to DEBUG mode to get the full traceback for GUI exceptions, but heed the warning regarding production systems before doing so.

Submitting Pull Requests

  • Please follow the NetBox Plugin Development Guide, regarding supported interfaces. Exceptions should be rare and be accompanied with a good explanation.
  • Make sure to open an issue before starting work on a pull request, and discuss your idea with the NetBox DHCP community before starting work.
  • Create a new branch, ideally with a name like fix/short-description-of-the-fix or feature/short-description-of-the-feature to make the project history more readable. PRs based on your main branch will not be accepted.
  • All new functionality must be accompanied by relevant tests where possible.
  • All code submissions should meet the following criteria, which are automatically checked by the GitHub CI workflow:
    • Python syntax is valid.
    • black code formatting is enforced.
    • ruff code checking is enforced.
    • /opt/netbox/venv/bin/manage.py test netbox_dhcp must run successfully.
  • Include a reference to the fixed bug or feature request in the description of the pull request, e.g. fixes #23. See the GitHub documentation for details.
  • If the main branch has moved on while you were working on a pull request, please do not merge but rebase your branch. Merging normally isn't usually necessary, and it creates merge commits that unnecessarily clutter the project's history.
  • Code generated by "AI" will not be accepted.

First Time Setup

  • Download and install the latest version of git.
  • Configure git with your username and email:
$ git config --global user.name 'your name'
$ git config --global user.email 'your email'
  • Fork netbox-plugin-dhcp to your GitHub account by clicking the Fork button.
  • Clone the your forked repository locally:
$ git clone https://github.com/YOUR-GITHUB-USERNAME/netbox-plugin-dhcp.git
  • Use the main project's main repository as upstream remote:
$ cd netbox-plugin-dhcp
$ git remote add upstream https://github.com/sys4/netbox-plugin-dhcp.git
  • Install NetBox. Please see the NetBox Installation Guide. The following steps assume that you followed that documentation and installed NetBox in /opt/netbox and the virtual environment in /opt/netbox/venv.
  • Activate the NetBox virtual environment (assuming your NetBox installation resides in /opt/netbox):
$ source /opt/netbox/venv/bin/activate
  • Install the black code formatter:
$ /opt/netbox/venv/bin/python3 -m pip install black
  • Install the ruff linter:
$ /opt/netbox/venv/bin/python3 -m pip install ruff
  • Install netbox-plugin-dhcp. In a development environment it makes most sense to use an editable installation, which can be achieved by the following commands (assuming you checked out the NetBox DHCP repository to /install-path/netbox-plugin-dhcp):
$ /opt/netbox/venv/bin/python3 -m pip -e /install-path/netbox-plugin-dhcp
  • Add NetBox DHCP to the NetBox configuration /opt/netbox/netbox/netbox/configuration.py
PLUGINS = [
    "netbox_dhcp",
]
  • Restart NetBox
# systemctl restart netbox netbox-rq

After these steps are completed successfully, you're all set up.

Code formatting and linting

To achieve a consistent coding style, all code for the NetBox DHCP plugin is formatted using the black formatter and checked for inconsistencies such as unused imports and variables using the ruff linter.

$ /opt/netbox/venv/bin/black netbox_dhcp
$ /opt/netbox/venv/bin/ruff check netbox_dhcp

Running the Tests

Go to the NetBox directory and run:

$ /opt/netbox/netbox/manage.py test netbox_dhcp.tests