Contributing guidelines

Codacy quality grade Codacy code coverage

Thanks for taking the time to contribute!

This project is simpler than most, so it’s a good place to start contributing to the open source community, even if you’re a newbie.

We are accepting these sorts of changes and requests:

We are not accepting things that should be done in your own wrapper code:

If you have general interest in contributing, but are not sure where to start, please contact us and we can help to find work in an area of interest.

Reporting bugs and feature requests

If you suspect a problem, please report a bug Issue with a detailed description of the problem, steps to reproduce, code samples, and any reference materials. For enhancements, create a feature Issue.

Use the Discussions area for general ideation and help/usage questions.

Project management

Developing

Testing

Performance benchmarking

Running the Tests.Performance console application in Release mode will produce benchmark performance data that we include on our documentation site.

# run all performance benchmarks
dotnet run -c Release

# run individual performance benchmark
dotnet run -c Release --filter *.GetAdx

Documentation

This site uses Jekyll construction with Front Matter. Our documentation site code is in the docs folder. Build the site locally to test that it works properly. See Ruby Jekyll documentation for initial setup.

# from /docs folder
bundle install
bundle exec jekyll serve -o -l

# the site will open http://127.0.0.1:4000

When adding or updating indicators:

Accessibility testing

npx pa11y-ci --sitemap http://127.0.0.1:4000/sitemap.xml

Submitting changes

By submitting changes to this repo you are also acknowledging and agree to the terms in both the Developer Certificate of Origin (DCO) 1.1 and the Apache 2.0 license. These are standard open-source terms and conditions.

When ready, submit a Pull Request with a clear description of what you’ve done and why it’s important. Always write a clear log message for your commits. One-line messages are fine for most changes.

After a Pull Request is reviewed, accepted, and [squash] merged to main, we may batch changes before publishing a new package version to the public NuGet repository. Please be patient with turnaround time.

Code reviews and administration

If you want to contribute administratively, do code reviews, or provide general user support, we’re also currently seeking a few core people to help. Please contact us if interested.

Standards and design guidelines

Versioning

We use the GitVersion tool for semantic versioning. It is mostly auto generated in the build.

Type Format Description
Major x.-.- A significant deviation with major breaking changes.
Minor -.x.- A new feature, usually new non-breaking change, such as adding an indicator. Minor breaking changes may occur here and are denoted in the release notes.
Patch -.-.x A small bug fix, chore, or documentation change.
Increment -.-.-+x Intermediate commits between releases.

This only needs to be done on the merge to main when the Pull Request is committed, so your feature branch does not need to include this as it will get squashed anyway.

A Git tag, in accordance with the above schema, is introduced automatically after deploying to the public NuGet package manager and is reflected in the Releases.

License

License

This repository uses a standard Apache 2.0 open-source license. It enables open-source community development by protecting the project and contributors from certain legal risks while allowing the widest range of uses, including in closed source software. Please review the license before using or contributing to the software.

Contact info

Start a new discussion or submit an issue if it is publicly relevant. You can also direct message @daveskender.

Thanks, Dave Skender