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
New reputable “by the book” indicators and overlays

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.
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.
If you are adding a new indicator, the easiest way to do this is to copy the folder of an existing indicator and rename everything using the same naming conventions and taxonomy. All new indicators should include tests.
Do not commingle multiple contributions on different topics. Please keep changes small and separate.

Testing

Review the tests/indicators folder for examples of unit tests. Just copy one of these.
New indicators should be tested against manually calculated, proven, accurate results. It is helpful to include your manual calculations spreadsheet in the appropriate indicator test folder when submitting changes.
Historical Stock Quotes are automatically added to unit test methods. A Data.Quotes.xlsx Excel file is included in the tests/_common folder that is an exact copy of what is used in the unit tests. Use a copy of this file for your manual calculations to ensure that it is correct. Do not commit changes to the original file.
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.

Performance benchmarking

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

# from /tests/performance folder
# 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 --livereload

The site will be available at http://127.0.0.1:4000.

When adding or updating indicators:

Add or update the /docs/_indicators/ documentation files.
Page image assets go here: /docs/assets/ and can be optimized to webp format using ImageMagick or the cwebp Encoder CLI and a command like cwebp -resize 832 0 -q 100 examples.png -o examples-832.webp

Accessibility testing

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

# from /docs folder
npx pa11y-ci \
  --yes
  --sitemap http://127.0.0.1:4000/sitemap.xml \
  --config ./.pa11yci

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.

Pull Request naming convention

Pull Request titles must follow the Conventional Commits format: type: Subject where:

type is one of: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert (lowercase)
Subject starts with an uppercase letter

Examples: feat: Add RSI indicator, fix: Resolve calculation error in MACD, docs: Update API documentation

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 the default branch, 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

GitHub Copilot and AI development

This repository is optimized for GitHub Copilot and coding agents with:

Custom Copilot instructions in .github/copilot-instructions.md providing repository context, coding patterns, and domain knowledge
Enhanced VS Code settings in .vscode/settings.json with Copilot-specific configurations for optimal suggestions
Development container in .devcontainer/devcontainer.json for consistent development environment setup
MCP server configurations in .vscode/mcp.json for extended AI tools for developing capabilities with financial mathematics and .NET performance analysis

When using GitHub Copilot:

Follow the established patterns documented in the Copilot instructions
Ensure all financial calculations maintain decimal precision
Include comprehensive unit tests for any new indicators
Validate mathematical accuracy against reference implementations

Versioning

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

Using these merge commit messages only needs to be done on the merge to main when the Pull Request is committed and need to reflect a minor or major version update. Incremental feature branch commits do not need to include this as it will get squashed anyway.

Adding +semver: major as a PR merge commit message will increment the major x.-.- element
Adding +semver: minor as a PR merge commit message will increment the minor -.x.- element
Adding +semver: patch as a PR merge commit message will increment the minor -.-.x element (default). Patch element auto-increments, so you’d only need to do this to override the next value.

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.

Version marker and suffix taxonomy

When the packager deployer runs, it will produce versions and naming follow these rules:

Trigger	Branch	Environment	Preview	Dry-run	Suffix	Example
Push	main	pkg.github.com	Yes	No	`-ci.X`	`2.6.2-ci.45`
Push	v*	pkg.github.com	Yes	No	`-ci.X`	`3.0.0-ci.16`
Manual	any	pkg.github.com	Yes	Yes	`-preview.N`	`3.0.0-preview.2`
Manual	any	nuget.org	Yes	Yes	`-preview.N`	`3.0.0-preview.2`
Manual	main	nuget.org	No	Yes	(none)	`2.6.2`
Manual	main	nuget.org	No	No	(none)	`2.6.2`

Legend:

Preview: If true, version gets a preview or CI suffix
Dry-run: If true, package is not published (for testing only)
Suffix: Shows how the version string is modified
Example: Illustrative version number for each scenario.

Additional info:

X is a sequential number based on the last CI publish.

R is a sequential number based on the last tagged production deployment.

Only a main non-dry-run trigger will tag the branch with an official release marker.

For more details, see the deploy-package.yml workflow.

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