Contributing ============ Thank you for your interest in contributing to ``TorchDR``! This library is a community-driven project, and we greatly appreciate contributions of all kinds. If you encounter any issues or have suggestions, please open an issue on our `issue tracker `_. This allows us to address problems and gather feedback from the community. For those who want to contribute code or documentation, you can submit a pull request. Below, you will find details on how to prepare and submit your pull request effectively. PR Tutorial ----------- The preferred workflow for contributing to ``TorchDR`` is to fork the `main repository `_ on GitHub, clone, and develop on a branch. Steps: 1. Fork the `project repository `_ by clicking on the 'Fork' button near the top right of the page. This creates a copy of the code under your GitHub user account. For more details on how to fork a repository see `this guide `_. 2. Clone your fork of the ``TorchDR`` repo from your GitHub account to your local disk:: $ git clone git@github.com:YourLogin/TorchDR.git $ cd TorchDR 3. Install the package in editable mode with the development dependencies, as well as the pre-commit hooks that will run on every commit:: $ pip install -e .[dev,doc] && pre-commit install 4. Create a branch to hold your development changes:: $ git checkout -b my-feature Always use a dedicated branch. It's good practice to never work on the ``main`` branch! 5. Develop the feature on your feature branch. Add changed files using ``git add`` and then commit the changes using ``git commit``:: $ git add modified_files $ git commit -m "Your commit message here" To record your changes in Git, then push the changes to your GitHub account with:: $ git push -u origin my-feature 6. Follow `these instructions `_ to create a pull request from your fork. Then, a project maintainer will review your changes. PR Checklist ------------ When preparing the PR, please make sure to check the following points: - The automatic tests pass on your local machine. This can be done by running ``python -m pytest torchdr/tests`` in the root directory of the repository after making the desired changes. - If your pull request addresses an issue, please use the pull request title to describe the issue and mention the issue number in the pull request description. This will make sure a link back to the original issue is created. - The documentation is updated if necessary. You can edit the documentation using any text editor and then generate the HTML output by typing ``make html`` from the ``docs/`` directory. The resulting HTML files will be placed in ``docs/build/html/`` and are viewable in a web browser. Use a ``[Type] Description`` format for your PR title, where type is one of: ``Feature``, ``Fix``, ``Refactor``, ``Doc``, ``Test``, ``Chore``. For example: ``[Fix] Resolve NaN in PHATE potential distance``. If your PR is not yet ready for review, open it as a `Draft Pull Request `_. Draft PRs are useful to: - Indicate that you are actively working on something to prevent duplicated efforts. - Request early feedback on functionality, design, or API. - Seek collaborators to assist with development. When your work is ready for review, click **Ready for review** to convert the draft into a regular PR. New contributor tips -------------------- A great way to start contributing to ``TorchDR`` is to pick an item from the list of `good first issues `_ in the issue tracker. Resolving these issues allows you to start contributing to the project without much prior knowledge.