Contributing

Before contributing to this repository, first please discuss the change you wish to make via an issue, or any other method of communication with the maintainers of this repository.

You can also search this project for issues with the following labels:

Label	Search Term	Description
good-first-issue	is:issue is:open label:good-first-issue	Recommended for first-time contributors! These are well-defined, and allow a user to get familiar with the project's workflow before tackling more complex issues.
help wanted	is:issue is:open label:"help wanted"	General issues where contributors help is wanted.
question	is:issue is:open label:question	Open discussions to resolve everything from implementation details to desired functionality.

Environment setup with GitHub Codespaces

To create a new Codespace, use the Code dropdown on the repository main page or click the button below. Follow the prompts and select "Memray development" for Dev container configuration if it isn't already selected. It should take approximately 1-2 minutes to setup.

Contribution Licensing

Since this project is distributed under the terms of an open source license, contributions that you make are licensed under the same terms. In order for us to be able to accept your contributions, we will need explicit confirmation from you that you are able and willing to provide them under these terms, and the mechanism we use to do this is called a Developer's Certificate of Origin (DCO). This is very similar to the process used by the Linux kernel, Samba, and many other major open source projects.

To participate under these terms, all that you must do is include a line like the following as the last line of the commit message for each commit in your contribution:

Signed-Off-By: Random J. Developer <random@developer.example.org>

The simplest way to accomplish this is to add -s or --signoff to your git commit command.

You must use your real name (sorry, no pseudonyms, and no anonymous contributions).

Documentation

Public modules, functions, classes, and methods must be documented using Python docstrings. Non-public functions and methods must also be documented for defining the API contract. In addition to being useful for generating documentation, docstrings add clarity when looking through the source code or using the built-in help system, and can be leveraged in autocompletion by IDEs.

Please see PEP 257 for details on semantics and conventions associated with Python docstrings.

Docstring style

Docstrings must follow Google style docstrings. This docstring style is more pleasant to read when browsing the source.

Type hints

All functions and methods should be type annotated. This allows for static analysis and more intelligent code completion from tools & IDEs.

Tests

Changes should always include tests. If this is a bug fix it is a good idea to add the tests as the first commit of the pull request and the changes to fix the issue in subsequent commits to make it easier to validate it.

Running tests

To run the test suite, first install the project and the test requirements:

python3 -m pip install -e . --group test

Note that you may need to use python3 -m pip install --upgrade pip before installing the test requirements to ensure you have a recent version of pip that supports the --group option.

Once the test dependencies are installed, you can run the full test suite by running:

make check

To run only the Python tests, you can instead run:

make check-python

Or to run only the JavaScript tests, you can run:

make check-js

Pull requests

Linting your code

Before commiting anything, install the prek (pre-commit) hooks:

python3 -m pip install --upgrade pip
python3 -m pip install --group extra
prek install

This will ensure that your contribution passes our linting checks.

PRs should be linked to a GitHub issue

Before opening a pull request to this repository, first please make sure there is a GitHub issue where your change has been discussed with the maintainers. Mention the issue number in your pull request description using one of the supported keywords. For example, adding Closes: #100 in the pull request description will link the PR with the issue and GitHub will automatically close the issue upon merging it.

Do not include the issue reference in your commit messages however, add it only in the description of the PR.