How to contribute¶

• How to contribute
• Setup the development environment
• Commit message guidelines
  • Commit message format
  • Types and emojis
  • Scope
  • Subject
  • Body
  • Footer
• Milestones
• Testing
• Submitting changes
  • Branching rules
• Coding conventions
• Note

We are really glad you're reading this, because we need volunteer developers to help this project SpectraFit.

Here are some important resources:

• Issues for open BUG reports or feature requests
• Pull requests for contributing code
• Milestones, which are listed below.

Setup the development environment¶

SpectraFit is using uv as python package management system and pre-commit for managing git hooks. For fixing bugs or developing new features, we recommend to use both tools. The python version should be 3.8.1 or higher and can be optional managed via pyenv.

# Setting up your Python environment
pyenv local 3.10.0

# Install dependencies with uv
uv pip install -e .

# Install development dependencies
uv pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install --install-hooks

Even if we have no git hook for code style in markdown, json, and yaml files, we prefer the prettier style and its extension for toml files.

Commit message guidelines¶

We follow the Conventional Commits specification for our commit messages. This leads to more readable messages that are easy to follow when looking through the project history.

Commit message format¶

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, an optional scope and a subject:

<type>[optional scope]: <emoji> <subject>
[optional body]
[optional footer(s)]

Examples:

feat: ✨ add new peak fitting method
fix: 🐛 handle NaN values in solver
docs: 📝 update usage documentation

Types and emojis¶

We use the following types and associated emojis:

Scope¶

The scope is optional and should be the name of the module affected (as perceived by the person reading the changelog generated from commit messages).

Subject¶

The subject contains a succinct description of the change:

• Use the imperative, present tense: "change" not "changed" nor "changes"
• Don't capitalize the first letter
• No dot (.) at the end

Body¶

The body should include the motivation for the change and contrast this with previous behavior.

Footer¶

The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit Closes.

Milestones¶

Milestones now also available for the spectrafit application. Furthermore, project status can be seen in the GitHub Project Panel.

Testing¶

We are using only GitHub-Actions for pre-commit testing, the CI/CD pipeline and the release.

Submitting changes¶

Please send a GitHub Pull Request to SpectraFit with a clear list of what you've done (read more about pull requests). We can always use more test coverage. Please follow our coding conventions (below) and make sure all of your commits are atomic (one feature per commit).

Always write a clear log message for your commits following our commit message guidelines.

In terms of connecting issues with the corresponding PR, we prefer to use the the GitHub convention of using the issue number in the commit message. This also allows us to easily linking PRs with issues in our Project Board.

Branching rules¶

We follow a Trunk-Based Development approach:

• All changes should branch from main
• Use short-lived feature branches named with the pattern: type/short-description Examples:
• feat/peak-fitting
• fix/nan-handling
• docs/usage-update
• Merge to main via pull request after review and passing CI
• Rebase frequently to keep branches up to date with main
• Delete feature branches after merge

Coding conventions¶

Start reading our code and you'll get the hang of it. We optimize for readability:

• We use as formaters for Python:
• 
• 
• 
• Google convention for docstrings
• We use as formater for Markdown, JSON and YAML files:
• 

Note¶

This template is adapted from opengovernment.