Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# Contributing

Contributions are welcomed via pull requests on GitHub. Contact the GSD developers before starting work to ensure it meshes well with the planned development direction and standards set for the project.

## Features

### Implement functionality in a general and flexible fashion

New features should be applicable to a variety of use-cases. The GSD developers can assist you in designing flexible interfaces.

### Maintain performance of existing code paths

Expensive code paths should only execute when requested.

## Version control

### Base your work off the correct branch

- Base backwards compatible bug fixes on `trunk-patch`.

- Base additional functionality on `trunk-minor`.

- Base API incompatible changes on `trunk-major`.

### Propose a minimal set of related changes

All changes in a pull request should be closely related. Multiple change sets that are loosely coupled should be proposed in separate pull requests.

### Agree to the Contributor Agreement

All contributors must agree to the Contributor Agreement before their pull request can be merged.

### Set your git identity

Git identifies every commit you make with your name and e-mail. Set your identity to correctly identify your work and set it identically on all systems and accounts where you make commits.

## Source code

### Use a consistent style

The Code style section of the documentation sets the style guidelines for GSD code.

### Document code with comments

Use doxygen header comments for classes, functions, etc. Also comment complex sections of code so that other developers can understand them.

### Compile without warnings

Your changes should compile without warnings.

## Tests

### Write unit tests

Add unit tests for all new functionality.

### Validity tests

The developer should run research-scale simulations using the new functionality and ensure that it behaves as intended.

## User documentation

### Write user documentation

Document public-facing API with Python docstrings in Google style.

### Example notebooks

Demonstrate new functionality in the documentation examples pages.

### Document version status

Each user-facing Python class, method, etc. with a docstring should have [`versionadded`, `versionchanged`, and `deprecated` Sphinx directives]

### Add developer to the credits

Update the credits documentation to name each developer that has contributed to the code.

### Propose a change log entry

Propose a short concise entry describing the change in the pull request description.