Skip to content

Contributing to CANFAR

Thank you for considering contributing to the canfar project! We welcome contributions from everyone. Please follow the guidelines below to help us maintain a high-quality codebase.

We follow the Contributor Convenant of Code of Conduct. If you wish to contribute to canfar, please make sure to familiarize yourself with it.

Contributions are not limited to just code. You can help us by:

How to Contribute Code

1. Fork the Repository

Start by forking the repository on GitHub. This will create a copy of the project under your GitHub account.

2. Clone Your Fork

Clone your forked repository to your local machine:

git clone https://github.com/your-username/canfar.git
cd canfar

3. Set Up Your Development Environment

To setup the development environment, simply run:

uv python install 3.13
uv venv --python 3.13
uv sync --all-extras --dev

These commands will install the Python version, create a virtual environment, and install all dependencies required for development.

Alternative Tooling

While this project uses uv for dependency and virtual environment management, you are welcome to use other tools like pip, conda, or virtualenv. The pyproject.toml file contains all the necessary information for these tools to create a compatible environment.

Skaha uses pre-commit to manage the development workflow. To install the pre-commit hooks, simply run:

uv run pre-commit install --hook-type commit-msg

4. Make Your Changes

Make your changes. Please make sure to add tests for your changes if applicable.

5. Run the Tests

To run tests for Skaha, you need to have a valid CANFAR account and access to the CANFAR Science Platform. To generate a certificate, please refer to the get started section.

uv run pytest

Running Tests Efficiently

Some tests in the Skaha test suite are marked as "slow" because they involve network operations, waiting for session states, or other time-consuming operations. These tests can take several minutes to complete.

Run all tests (including slow ones): 

uv run pytest

Skip slow tests for faster development: 

uv run pytest -m "not slow"

Run only slow tests: 

uv run pytest -m "slow"

The slow tests are primarily integration tests that interact with the CANFAR Science Platform and include: - Session creation and management tests - Log retrieval tests - Authentication timeout tests - Session statistics tests

For rapid development and testing, it's recommended to use -m "not slow" to skip these time-consuming tests during your development cycle, and run the full test suite before submitting your pull request.

6. Commit Your Changes

Skaha uses the conventional commit messages standard to ensure the commit history human and machine readable. Skaha ships with a tool called commitizen that helps you craft commit messages in the correct format.

git add files/you/changed.py
uv run cz commit

At this point, you will also see pre-commit hooks running to check your code for any issues and ensure that the code is linted and formatted correctly.

7. Push Changes to Your Fork

Push your changes to your forked repository:

git push

8. Create a Pull Request

Once your changes are pushed to your fork, you can create a pull request from your forked repository to the main Skaha repository. The maintainers will review your changes and merge them if everything is in order.

9. Celebrate

Congratulations! You've made it through the contribution process! Now it's time to celebrate your hard work. Here are a few fun ways to do so:

  • Dance Party: Put on your favorite tunes and have a solo dance party in your living room. Bonus points for using a disco ball!
  • Snack Attack: Treat yourself to your favorite snack. Whether it's pizza, ice cream, or a healthy smoothie, you deserve it!
  • Virtual High-Five: Send a virtual high-five to your fellow contributors. You can even use a GIF for extra flair!
  • Meme It Up: Create a meme about your contribution journey. Share it in the Discussions board for a good laugh!
  • Celebrate with Code: Write a fun piece of code that does absolutely nothing but prints "I did it!" to the console. Because why not?

Remember, every contribution counts, and you’ve just made the Skaha project a little better. Now go forth and celebrate like the coding rockstar you are!