Contributing

We welcome contributions to AMBER! This guide will help you get started.

Getting Started

Fork the Repository

Fork the AMBER repository on GitHub and clone your fork:
```
git clone https://github.com/your-username/AMBER.git
cd AMBER
```

Set Up Development Environment

Create a virtual environment and install development dependencies:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

Run Tests

Make sure all tests pass before making changes:
```
pytest tests/
```

Types of Contributions

Bug Reports

Report bugs using GitHub Issues. Include: - Clear description of the problem - Steps to reproduce - Expected vs actual behavior - System information (OS, Python version, AMBER version)

Feature Requests

Suggest new features using GitHub Issues. Include: - Clear description of the feature - Use case and motivation - Proposed API (if applicable)

Code Contributions

Bug fixes
New features
Performance improvements
Documentation improvements

Documentation

Fix typos and improve clarity
Add examples
Translate documentation

Development Workflow

Create a Branch

git checkout -b feature/your-feature-name

Make Changes
- Write code following our style guidelines
- Add tests for new functionality
- Update documentation as needed

Test Your Changes

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_model.py

# Run with coverage
pytest tests/ --cov=ambr

Commit Changes

git add .
git commit -m "Add feature: description of changes"

Push and Create Pull Request
```
git push origin feature/your-feature-name
```
Then create a pull request on GitHub.

Code Style Guidelines

Python Style

Follow PEP 8
Use type hints where appropriate
Write docstrings for all public functions and classes
Use meaningful variable and function names

Testing

Write tests for all new functionality
Aim for high test coverage
Use descriptive test names
Include both unit and integration tests

Documentation

Update docstrings for API changes
Add examples for new features
Update tutorials if relevant

Pull Request Guidelines

Before Submitting

Ensure all tests pass
Update documentation
Add entry to changelog (if applicable)
Rebase on latest main branch

Pull Request Description

Clear title summarizing the change
Detailed description of what was changed and why
Link to related issues
Screenshots for UI changes (if applicable)

Review Process

All PRs require review from maintainers
Address feedback promptly
Keep PRs focused and reasonably sized
Be patient - reviews take time

Release Process

AMBER follows semantic versioning:

Major (x.0.0): Breaking changes
Minor (0.x.0): New features, backward compatible
Patch (0.0.x): Bug fixes, backward compatible

Before tagging a release:

Make sure dev is up to date with origin/dev and merged or fast forwarded into main for release.
Bump the package version in pyproject.toml and update CHANGELOG.md plus docs/changelog.rst.
Run make release-check from a clean checkout. This builds the wheel and source distribution, runs twine check, and executes the test suite.
Inspect the source distribution if local generated artifacts exist; paper drafts and paper.zip must remain ignored and excluded from the package.
Create and push an annotated vX.Y.Z tag from the release commit. The GitHub release workflow validates the distributions again and attaches them to the GitHub release.

Community Guidelines

Be Respectful

Use welcoming and inclusive language
Respect differing viewpoints
Focus on constructive feedback

Be Collaborative

Help others learn and contribute
Share knowledge and expertise
Acknowledge contributions

Be Patient

Maintainers are volunteers
Reviews and responses take time
Complex changes require thorough review

Getting Help

If you need help:

Check existing documentation
Search GitHub Issues
Ask questions in discussions
Contact maintainers directly

Thank you for contributing to AMBER!