Contributing to sed#

Welcome to the sed project, a collaboration of the Open Community of Multidimensional Photoemission Spectroscopy.

Whether you are a beamline scientist hoping to create a loader for your data, or would like to add a new feature to the project, we welcome your contributions.

This guide will walk you through the process of setting up your development environment, and the workflow for contributing to the project.

Getting Started#

  1. Clone the Repository:

    • If you are a member of the repository, clone the repository to your local machine:

    git clone https://github.com/OpenCOMPES/sed.git

    • If you are not a member of the repository, clone your fork of the repository to your local machine:

    git clone https://github.com/yourusername/sed.git

  2. Install uv and Python: Ensure you have uv and Python 3.9, 3.10, 3.11 or 3.12 installed. You can install it e.g. using the following commands:

    curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.10

  3. Clone Repository:

    git clone https://github.com/OpenCOMPES/sed.git

  4. Set up virtual environment: Create a python virtual environment, and activate it. You can optionally select the python version, and set the path

    uv venv -p=3.10 .venv
source .venv/bin/activate

  5. Install Dependencies: Navigate to the project directory and install the project and its dependencies (including development ones) in “editable” mode using uv. Optionally, the jupyter notebook can be installed as well:

    uv pip install -e .[dev,notebook]

Development Workflow#

Note

This guide assumes that you followed the previous steps and have uv, python and the package with dev dependencies installed on your machine.

  1. Install pre-commit hooks: To ensure your code is formatted correctly, install pre-commit hooks:

    pre-commit install

  2. Create a Branch: Create a new branch for your feature or bug fix and make changes:

    git checkout -b feature-branch

  3. Write Tests: If your contribution introduces new features or fixes a bug, add tests to cover your changes.

  4. Run Tests: To ensure no functionality is broken, run the tests:

    pytest tests

  5. Commit Changes: Commit your changes with a clear and concise commit message:

    git commit -a -m "Your commit message"

  6. Push Changes: Push your changes to your new branch:

    git push origin feature-branch

  7. Open a Pull Request: Open a pull request against the main branch of sed.

Pull Request Guidelines#

Please give a brief description of the changes you have made in your pull request. If your pull request fixes an issue, please reference the issue number in the pull request description.

Before your pull request can be merged, it must pass the following checks:

  • Linting Check

  • Tests Check

  • Code Review: A maintainer will review your code and provide feedback if necessary.

  • Rebase with Main: Ensure your branch is up-to-date with the latest changes from the main branch.

Once all checks are successful and your code is approved, it will be merged into the main branch.

Developing a Loader#

If you are developing a loader for your beamline, please follow the guidelines below.

  1. Create a Loader:

    • Create a new loader in the sed/loaders directory.

    • The loader should be a subclass of sed.loader.base.loader.BaseLoader and implement a few methods. See Abstract BaseLoader for more information.

    • Give your class a __name__ attribute, which is used to select the loader in user config files (See the generic loader for example).

    • At the end of your module, provide a LOADER = YourNameLoader variable, which is used to register that loader in the registry. See Loader Interface.

  2. Write Tests:

    • Write tests for your loader in the tests/loaders directory.

    • You can also include a small test data in the tests/data directory.

  3. Add Loader to Documentation: Add your loader to the documentation in docs/sed/loaders.rst.