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

We have different places to take issues by its category.

If you are reporting a bug or suspect a problem, please submit an issue with a detailed description of the problem + include steps to reproduce, code samples, and any reference materials.

🔧 Report bugs

For new features, submit an issue with the enhancement label.

💡 Request features

• 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.
• Use the Discussions area for general ideation and unrelated questions.

• Recommended tools: Git, Python 3.8+, Docker (optional), and Visual Studio Code (see .vscode/extensions.json for recommended extensions).
• This project supports VS Code Dev Containers for a consistent development environment. Open the project in VS Code and select "Reopen in Container" (requires the Dev Containers extension).
• Local installs are plain pip + venv; no Poetry/Conda/Hatch required.

• Read this first: A Step by Step Guide to Making Your First GitHub Contribution. If you have questions about forking, see this discussion.
• Please keep contributions small and focused—avoid combining unrelated changes in one pull request.
• If you're just getting started, make sure to install and set up the language SDKs for Python and .NET (see below for setup instructions).

1. Install .NET SDK (8.0 or newer):

   winget install Microsoft.DotNet.SDK.8
   # Or download from https://dotnet.microsoft.com/download

2. Clone and setup:

   git clone https://github.com/facioquo/stock-indicators-python.git
   cd stock-indicators-python
   python -m venv .venv
   .venv\Scripts\python -m pip install --upgrade pip
   .venv\Scripts\python -m pip install -e .
   .venv\Scripts\python -m pip install -r requirements-test.txt

1. Install .NET SDK (8.0 or newer):

   brew install dotnet-sdk

2. Clone and setup:

   git clone https://github.com/facioquo/stock-indicators-python.git
   cd stock-indicators-python
   python -m venv .venv
   source .venv/bin/activate
   python -m pip install --upgrade pip
   python -m pip install -e .
   python -m pip install -r requirements-test.txt

• We use Ruff for linting/formatting, Pyright for type checking, and pytest for tests. pip-audit runs in CI.
• Review the tests 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 folder when submitting changes.
• Historical Stock Quotes are automatically added as pytest fixtures. The various .csv files in the samples folder are used in the unit tests. See tests/conftest.py for their usage. A History.xlsx Excel file is also included in the samples folder that contains the same information but separated by sheets. Use this for your manual calculations to ensure that it is correct. Do not commit changes to this Excel 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.

Common commands (after activating .venv):

# lint and format
python -m ruff check .
python -m ruff format --check .

# type-check
python -m pyright

# run standard unit tests
python -m pytest

To run different types of tests:

• Non-standard localization tests:

  python -m pytest -m "localization"

• Performance tests:

  python -m pytest -m "performance"

• All tests (not recommended):

  python -m pytest -m ""

You can also use the -svr A arguments with pytest to get more detailed output:

• -s: Disable output capturing (show print statements)
• -v: Increase verbosity
• -r A: Show extra test summary info for all tests

pytest -svr A

Running the commands below in your console will produce benchmark performance data that we include on our documentation site.

# install dependencies
python -m pip install -r requirements-test.txt

# run performance tests
python -m pytest -m "performance"

This site uses 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 Pages documentation for initial setup instructions.

bundle install
bundle exec jekyll serve

# then open site on http://127.0.0.1:4000,
# or use `bundle exec jekyll serve -o -l` to auto-open, livereload

When adding or updating indicators:

• Add or update the indicator documentation /docs/_indicators files.
• Page image assets go in the /docs/assets/ folder.

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 (read more about pull requests). 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 PyPI. Please be patient with turnaround time.

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.

• PEP 8 -- Style Guide for Python Code
• PEP 440 -- Version Identification and Dependency Specification
• Semantic Version 2.0
• Python Packaging User Guide

We use the setuptools_scm tool for semantic versioning. It detects the version number from git tag in the GitHub Actions build.

After one of our repository administrators creates a git tag on the main branch, reflecting the new version number, the PyPI deployment workflow will start. After the new package is published, they'll publicly post the release record with automatically generated notes and other information.

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.

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

Thanks, Dong-Geon Lee Dave Skender