Skip to content

Latest commit

聽

History

History
132 lines (85 loc) 路 5.44 KB

CONTRIBUTING.md

File metadata and controls

132 lines (85 loc) 路 5.44 KB
Raw

Contributing to RADIS

We love spectroscopy, and we love your input! We want to make contributing to this project as easy as possible, whether it's:

  • Reporting a bug
  • Discussing the current state of the code or the physics
  • Submitting a fix
  • Proposing new features (interface or physics)
  • Becoming a core developer

This document is a quick summary, more information can be found on the Developer Guide

Report bugs using GitHub's issues

We use GitHub issues to track public bugs. Report a bug by opening a new issue; it's that easy!

Great Bug Reports tend to have:

  • A quick summary and/or background
  • Steps to reproduce : specific, with code samples if possible
  • What you expected would happen
  • What actually happens
  • Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)

Issues labeled Good First Issue are also a nice way to get started with contributing to the project.

Ask questions

Join the community chat:

Slack Gitter

Propose new features

You can suggest or vote for new features below:

Feature Requests

Change the code : become a Contributor.

We use the GitHub Flow, where all code changes should happen through Pull Requests (PR). PR are the best way to propose changes to the codebase : Maintainers of the code can comment, help you, and even edit your code directly.

  1. Fork the repo : this creates your own RADIS version.
  2. If it's an easy fix (ex : fix a typo, update a single file, ...), edit it online on your Fork then open the PR (go directly to 6.)
  3. Else, Clone your fork : this adds RADIS on your local computer.

git clone https://github.com/[YOUR-USERNAME]/radis.git

  1. Time to work now : make your changes locally ! If you plan to work on multiple fixes at the same time, create a new branch (with a descriptive name) for your feature.

  2. Push your changes and open a Pull request (PR). If things aren't final, it's okay: just mark is as a draft [WIP]. Maintainers will review and start helping you from there !

  3. Once the review is complete (physical tests + code linting), the pull request is merged : welcome to the RADIS contributors ! 馃憦

TODO : add a .gif for the SmartGit/GitHub Desktop version ?

Where to start ?

If it's your first time contributing to an open-source project, welcome ! 馃憢

The best is to get familiar with the procedure above. For instance, there are many tiny improvements to be made to the Documentation :

  • Have a look at the Documentation TODO List.
  • Pick one of them, create your GitHub account, and start the procedure above to become a Contributor.

Then, have a look at the GitHub opened issues. Easy issues that will help you understand the code structure are labelled as Good First Issue.

Regular Contributor ? Keep your Fork updated.

If you keep on using your own local RADIS version, you want to keep it updated with the main branch. In usual Git Flow, your own Fork [YOUR-USERNAME]/radis is refered to as origin, and the main repo radis/radis as upstream.

One workflow is to have at least 2 branches locally :

  • one pointing to the latest developer version, e.g. named, upstream-develop.
  • one per feature or fix you're currently working on, pointing to your own fork origin : could be develop, fix/something, this_new_idea_i_work_on , etc.

A way to do this is to :

  1. set-up another remote :
git remote add upstream git://github.com/radis/radis.git
git fetch upstream
  1. Starting a new fix/feature ? Branch from the latest upstream-develop.
git branch -b [NEW_BRANCH] upstream/develop
  1. Need to update your local branch, by 'rebasing', i.e. without creating a merge-commit for the changes that were done by others :
git pull --rebase upstream [NEW_BRANCH]
  1. Push your changes to your own Fork
git push -u origin [NEW-BRANCH]
  1. Open a PR, as in "Become a Contributor" above.

Linting : use a Consistent Coding Style

We're using the Black coding style, and Flake8 to ensure no syntax errors are introduced. If you're a first time contributor, do not worry about Linting. Other developers will do it for you.

Once you're a regular contributor, we advise you install pre-commit that will take care of all the formatting :

cd radis
pre-commit install

See the Developer Guide for more information.

License

By contributing, you agree that your contributions will be licensed under the GNU Lesser General Public License v3.0

References

This document was adapted from the open-source contribution guidelines of @briandk