-
Notifications
You must be signed in to change notification settings - Fork 121
Contributing
Are you really digging BloodHound Community Edition and looking to give back to the project? Lucky for you there are numerous ways to help! Here are some recommendations to help get you started.
- Peruse the issue tracker on GitHub. This can be a great place to get started as it doesn't require much insider knowledge. Here's a few ideas that could help here.
- Open a bug or feature request
- Help others
- Enhance documentation
- Fix errors or inconsistencies
- Add documents for undocumented capabilities
- Write some code!
- Fixing a bug that has been reported
- Add a new feature
- Enhance an existing feature
First, thank you so much for considering a code contribution to BloodHound Community Edition. We're very appreciative of anyone who offers to give back to a tool they find useful. It helps make BloodHound better for everyone.
The following are some general guidelines to follow while writing and submitting your PRs. Following these should make merging the PR faster and easier.
If you need to get you development environment set up you should check out the guide here.
All PR submissions will need to come from a separate branch from main. We recommend creating a personal fork of the BloodHound repo and creating the branch from there. This will allow you more control over your local environment.
Also, please ensure that you are branching off of the latest version of main from the SpecterOps/BloodHound repo. This will ensure everything is built on top of the latest code and also help reduce merge conflicts.
Lastly, we ask that you use brief, but detailed, commit messages when writing your code. These will help with the review process as it will be easier to see the reasoning and details included in a particular change. Another habit that will help the PR reviewer is authoring smaller, frequent commits as opposed to a giant single commit containing all of your changes.
BloodHound CE follows standard Go styling and formatting practices. Please ensure that gofmt is run against your code before pushing up the PR by running gofmt -s -w from the root directory.
Alternatively, you can install goimports which has some added functionality for tidying up dependencies along with the gofmt functionality.
The entire BloodHound test suite will run against your PR once it is submitted. This includes Go unit tests, UI unit tests, and integration tests. All tests must pass for the PR to be landed.
If you see test failures on GitHub and want to troubleshoot them locally you can run them using the instructions [here](TODO: Link to testing section of development)
Most importantly, please consider adding test coverage around the new feature or bug fix that you are contributing. This will ensure that this new code retains resiliency as the code-base shifts around.
Documentation that is easy to read and understand is key to ensuring your new feature gets used. There are a number of places where this documentation can be added. We'll leave it up to you to decide where the best location is.
Code comments are the first place to begin documentation. Function-level comments are always appreciated for any new functions that are added, especially library functions. The standard Go Doc format is preferred. In-line comments are helpful for explaining why non-obvious code paths are used or walking through complex logic in a more human-readable way.
API updates should be documented in our OpenAPI specs located at cmd/api/src/docs/json/. Schema definitions are stored in the cmd/api/src/docs/json/definitions/ folder and then referenced within the endpoint definitions, which are stored in cmd/api/src/docs/json/paths/v2/. Please follow OpenAPI v3.0 specification standards when updating API documentation. More information can be on the [Code page](TODO: Link to API documentation on code page).
Lastly, if appropriate your feature may need to be documented on our official documentation page. Please reach out to the BloodHound team to discuss further.