Contributing guidelines

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:

Bug reports and fixes
Usability improvements
Documentation updates

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

Personal customizations and preferences
Modified or augmented outputs that are not intrinsic

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

Planned work is managed in the backlog alongside our .NET library work.
Work items are primarily entered as Notes (not Issues), except where an issue or feature is user reported. With that said, Notes can be converted to Issues if in-progress and collaborative discussion is needed.

Developing

Read this first: A Step by Step Guide to Making Your First GitHub Contribution. I also have a discussion on Forking if you have questions.
If you want to work on something specific, please mention your intention on the related Issue. If an Issue does not exist for your contribution, please create one before starting. This will help us reserve that feature and avoid duplicative efforts.
Do not commingle multiple contributions on different topics. Please keep changes small and separate.

Local hosting

From the Visual Studio Solution Explorer, select the Api project and then CTRL+F5 to launch the API. Or use CLI:

dotnet build
dotnet run --project src/Api.csproj

Root endpoint is hosted as https://localhost:[port] and should show a API is functioning nominally message in your browser.
OpenAPI (Swagger) documentations is available on https://localhost:[port]/swagger

Testing

Review the test folder for examples of unit tests. Just copy one of these.
We expect all unit tests to execute successfully and all Errors and Warning resolved before you submit your code.
Failed builds or unit testing will block acceptance of your Pull Request when submitting changes.

Documentation

This site uses GitHub Pages and Jekyll construction with Front Matter. The documentation site is in the docs folder. Build the site locally to test that it works properly. See GitHub documentation for initial Ruby and Jekyll setup instructions for Github Pages.

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

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

Accessibility testing

use Lighthouse in Chrome, or
build the site locally (see above), then:

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 list of what you’ve done. 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 packaged version. 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

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