This contribution guide was adapted from The Turing Way's contribution guide. See Contributing to The Turing Way.
- Get in touch
- Setting up VORTEX for development
- Contributing using GitHub
- Continuous integration checks
- GitHub issues and pull requests
- Join a discussion, collaborate on an ongoing task and exchange your thoughts with others.
- Can't find your idea being discussed anywhere? Open a new issue! (See our Where to start: issues section below.)
- Support mailing list
- You can email support queries at
vortex-support@meteo.fr. Please, however, favor GitHub issues over this mailing list. They allow other users and developers to contribute to the solution and to benefit from it.
- You can email support queries at
Start with cloning the vortex repository, for example:
git clone https://github.com/UMR-CNRM/vortex
It is highly recommended that you install vortex in a Python virtual environment, so as to isolate it and its dependencies from Python libraries that are already installed on your system, or that you will install in the future.
After creating and activating a Python virtual environment, install vortex in editable mode:
pip install --editable .[docs]
The --editable option ensures that you won't have to reinstall vortex everytime you make a change to it, see Development Mode.
The [docs] suffix indicates that you want pip to install the optional set of dependencies required to build the documentation website locally.
Then add both directories src and site to the PYTHONPATH environment variable.
Git is a really useful tool for version control. GitHub is web-based software that sit on top of Git and facilitates collaborative and distributed working.
It can be daunting to start using Git and GitHub if you haven't worked with them in the past, but the vortex team is here to help you figure out any of the jargon or confusing instructions you encounter.
In order to contribute via GitHub, you'll need to set up an account and sign in.
Most of the writing that you will do will be in Markdown.
You can think of Markdown as a few little symbols around your text that will allow GitHub to render the text with a little bit of formatting.
For example, you could write words as bold (**bold**), or in italics (_italics_), or as a [link][rick-roll] ([link](https://youtu.be/dQw4w9WgXcQ)) to another webpage.
You'll find a useful guide outline the basic syntax of Markdown at markdownguide.org.
When writing in Markdown, please start each new sentence on a new line. Having each sentence on a new line will make no difference to how the text is displayed, there will still be paragraphs, but it makes the diffs produced during the pull request review easier to read! ✨
Before you open a new issue, please check if any of our open issues cover your idea already.
Issues don't have to be technical: they could be about documentation you find unclear or missing, ideas for new features, or suggestions on how to make a part of vortex better.
We appreciate all contributions to vortex, whether they include changes to code itself or the documentation.
The following steps are a guide to help you contribute in a way that will be easy for everyone to review and merge your work into the project.
1. Comment on an existing issue or open a new issue referencing your contribution
This allows other members of vortex team to confirm that you aren't overlapping with work that's currently underway and that everyone is on the same page with the goal of the work you're going to carry out.
This blog is a nice explanation of why putting this work in upfront is so useful to everyone involved.
Start with creating a new Git branch from where you will make your changes.
Please start this branch from a recent copy of the main branch.
You can update your local copy with git pull
git switch main
git pull origin mainThen create and switch to your new branch with git switch:
$ git switch -c main
Are you new to Git and GitHub or just want a detailed guide on getting started with version control? Check out the Version Control chapter in The Turing Way Book!
Try to keep the changes focused. If you submit a large amount of work all in one go it will be much more work for whoever is reviewing your merge request.
While making your changes, commit often and write detailed commit messages. This blog explains how to write a good Git commit message and why it matters. It is also perfectly fine to have a lot of commits - including ones that break code. It is often difficult to assess or frequently you should push your changes to the GitHub repository. Think of pushing changes as sharing your work with other developers involved in the project. Pushing everytime you commit a change is uncessery, but waiting too long before making your work -- even incomplete -- available will make it very difficult for anyone to follow your progress. Worse, it will make it much harder for maintainers to review your contribution.
4. Submit a pull request
We encourage you to open a merge request as early in your contributing process as possible. This allows everyone to see what is currently being worked on and provides you, the contributor, feedback in real-time from the community.
The pull request description section is very important. A good description can make the contribution process dramatically faster, but a short, vague description will almost certainly slow it down. A a rule of thumb, a pull request description should, at the minimum, feature the following information:
- An accurate description of the problem you're trying to fix in the merge request, with reference(s) to any related issue(s).
- A list of changes proposed in the merge request.
In addition, it is often beneficial to include a description of what the reviewer(s) should concentrate their feedback on.
If you have opened the merge request early and know that its contents are not ready for review or to be merged, convert it to a draft. When you are happy with it and are happy for it to be merged into the main repository, mark it as ready for review.
One or more of vortex team members will then review your changes to confirm that they can be merged into the main repository. A review will probably consist of a few questions to help clarify the work you've done. Keep an eye on your GitHub notifications and be prepared to join in that conversation.
This is an alternative to creating and pushing your own branch to the vortex repository. This is the only way to contribute to the project is your GitHub account does not yet have persmission to push a branch to the vortex repository.
The vortex repository GitHub page offers a fork button that can be used to create a personal copy of the project, under your personal GitHub account. This copy, commonly known as fork is a completely separate repository from the original one.
You can contribute changes made in a fork back to the upstream repository. However, two pieces of advice:
- Make sure to keep your fork up to date with the main repository, otherwise, you can end up with lots of dreaded merge conflicts.
- Read https://hynek.me/articles/pull-requests-branch/.