Skip to content

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:

  • Reporting a bug
  • Discussing the current state of the code
  • Submitting a fix
  • Proposing new features
  • Becoming a maintainer

General Tips for Working on GitHub

  • Register for a free GitHub account if you haven't already.
  • You can use GitHub Markdown for formatting text and adding images.
  • To help mitigate notification spam, please avoid "bumping" issues with no activity. (To vote an issue up or down, use a 👍 or 👎 reaction.)
  • Please avoid pinging members with @ unless they've previously expressed interest or involvement with that particular issue.
  • Familiarize yourself with this list of discussion anti-patterns and make every effort to avoid them.

Types of Contributions

Report Bugs

Report bugs at GitHub Issues.

If you are reporting a bug, please include:

  • Your operating system name and version
  • Your NetBox version
  • Your Python version
  • Any details about your local setup that might be helpful in troubleshooting
  • Detailed steps to reproduce the bug

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with "bug" and "help wanted" is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with "enhancement" and "help wanted" is open to whoever wants to implement it.

Write Documentation

NetBox HealthCheck Plugin could always use more documentation, whether as part of the official docs, in docstrings, or even on the web in blog posts and articles.

Submit Feedback

The best way to send feedback is to file an issue at GitHub Issues.

If you are proposing a feature:

  • Explain in detail how it would work
  • Keep the scope as narrow as possible, to make it easier to implement
  • Remember that this is a volunteer-driven project, and that contributions are welcome!

Development Setup

Ready to contribute? Here's how to set up the plugin for local development:

1. Fork and Clone

Fork the repository on GitHub and clone your fork locally:

git clone git@github.com:your_username/netbox-healthcheck-plugin.git
cd netbox-healthcheck-plugin

2. Set Up NetBox Development Environment

Follow the NetBox Development Environment Guide to set up NetBox for plugin development.

Activate the NetBox virtual environment:

source ~/.venv/netbox/bin/activate

3. Install Plugin in Development Mode

Install the plugin in editable mode with development dependencies:

pip install -e ".[test,docs]"

This creates symbolic links within your Python environment to the plugin development directory.

4. Install Pre-commit Hooks

Install pre-commit hooks to automatically check code quality:

pre-commit install

5. Create a Feature Branch

Create a branch for your changes:

git checkout -b name-of-your-bugfix-or-feature

Now you can make your changes locally.

Development Workflow

Code Style

This project uses Ruff for linting and formatting:

# Check for linting issues
ruff check .

# Automatically fix issues
ruff check --fix .

# Format code
ruff format .

Pre-commit hooks will automatically run these checks before each commit.

Running Tests

Run the test suite using pytest:

pytest

Or using NetBox's test runner:

cd /path/to/netbox
python manage.py test netbox_healthcheck_plugin

Building Documentation

Build and preview documentation locally:

mkdocs serve

Then open http://127.0.0.1:8000 in your browser.

Testing with NetBox

To test the plugin with a running NetBox instance:

  1. Ensure the plugin is installed in development mode (step 3 above)
  2. Add the plugin to NetBox's configuration.py:
PLUGINS = ['netbox_healthcheck_plugin']
PLUGINS_CONFIG = {
    "netbox_healthcheck_plugin": {}
}
  1. Restart NetBox
  2. Visit the health check endpoint: /plugins/netbox_healthcheck_plugin/healthcheck/

Pull Request Guidelines

Before submitting a pull request:

  1. Include tests - The PR should include tests for new functionality
  2. Update documentation - Update docs for new features or changed behavior
  3. Follow code style - Ensure Ruff checks pass
  4. Update CHANGELOG.md - Add an entry describing your changes
  5. Test across Python versions - The PR should work for Python 3.12, 3.13, and 3.14

Check the GitHub Actions status to ensure all checks pass.

Commit Messages

Write clear, descriptive commit messages:

  • Use present tense ("Add feature" not "Added feature")
  • Use imperative mood ("Move cursor to..." not "Moves cursor to...")
  • Limit the first line to 72 characters or less
  • Reference issues and pull requests liberally after the first line

Submitting Changes

  1. Commit your changes:
git add .
git commit -m "Your detailed description of changes"
  1. Push to your fork:
git push origin name-of-your-bugfix-or-feature
  1. Submit a pull request through GitHub

Release Process

For maintainers:

  1. Ensure all changes are committed and tests pass
  2. Update version in pyproject.toml and netbox_healthcheck_plugin/__init__.py
  3. Update CHANGELOG.md with release notes
  4. Create a new release on GitHub with a version tag (e.g., v0.3.0)
  5. GitHub Actions will automatically publish to PyPI

Questions?

If you have questions or need help, please:

Thank you for contributing!