Contributing#

NPyComp is an open-source initiative. Contributions are welcome and appreciated.

Quick reference#

NPyComp uses the following conventions for contributing to the project. If you are familiar with these conventions, feel free to ignore the rest of guide.

Fork & Pull: The project follows the Fork & Pull model for contributions.
Tests: Write tests for your code using the pytest framework.
Linting: Use ruff for linting code.
Documentation: Use `Numpydoc style`_ docstrings for documenting code.
Commit Messages: Use the Conventional Commits specification for commit messages.
Versioning: NPyComp uses Semantic Versioning for versioning.

Detailed Reference#

Contributions to the project can be made using the “Fork & Pull” model. The typical steps are:

Setup your development environment by forking the repository and installing dependencies (see Development Environment).
Implement your changes. Use the Ruff linter to ensure your code conforms to the accepted style. (see Linting).
Implement the appropriate tests (see Testing).
Commit changes git commit -a -m "my message" (see Commit Messages).
Create a Pull Request (PR) from your GitHub fork (see GitHub PR instructions).

Otherwise, if you encounter any bugs or have an idea for a new feature but don’t have the time to implement it, please open an issue on the GitHub Issues.

Development Environment#

Fork the Repository: Start by forking the NPyComp repository on GitHub.
Clone the Repository: Clone your forked repository to your local machine.
```
git clone https://github.com/yourusername/npycomp.git
cd npycomp
```

Create a Virtual Environment: Set up a virtual environment to manage dependencies.

python3 -m venv venv
source venv/bin/activate  # On Windows, use `venv\Scripts\activate`

Install Dependencies: Install the package in “editable” mode, along with the development dependencies.
```
pip install --editable .
pip install -r requirements/all.txt
```
Run Tests: Run the test suite to ensure the setup is working correctly.
```
pytest
```

Linting#

The project uses ruff for linting code. The linter is configured to enforce the `Google style`_ guide for Python code.

To lint the code, run the following command:

ruff check

This command will check the code for any style violations and provide suggestions for fixing them. You should ensure that your code passes the linter before submitting a Pull Request.

Testing#

If you make a contribution to the code, please write a test for it. NPyComp uses the pytest framework. Create new test files in the tests/ directory, using the naming convention test_<feature>.py. Use one of the existing tests as a guide.

Run the tests using the command below to ensure everything works as expected.

pytest --cov=npycomp

You should see a summary of the test results and code coverage. If any tests fail, you should try and fix the issues before submitting a Pull Request.

Commit Messages#

NPyComp uses the Conventional Commits specification for commit messages. This format helps automate the release process and generate changelogs. The format is as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer]

The type is one of the following:

feat: A new feature
fix: A bug fix
docs: Documentation changes
style: Changes that do not affect the meaning of the code (white-space, formatting, etc.)
refactor: A code change that neither fixes a bug nor adds a feature
perf: A code change that improves performance
test: Adding missing tests
chore: Changes to the build process or auxiliary tools and libraries

The scope is optional and can be anything specifying the location of the commit change.

The description should be a short, imperative sentence that describes the change.

The body is optional and should provide a more detailed description of the change. Use the body to explain what and why vs. how.

The footer is optional and can be used to reference issues or pull requests.

For example:

feat(solvers): added XYZ solver

A new solver based on the XYZ algorithm.