# Contributing to _Environmental Data Science book (or EDS book)_

:earth_americas::earth_africa::earth_asia: **Welcome to _EDS book_ repository!** :earth_americas::earth_africa::earth_asia:

:green_heart: _We're excited that you're here and want to contribute._ :green_heart:

We want to ensure that every user and contributor feels welcome, included and supported to participate in the _EDS book_ community.
We hope that the information provided in this document will make it as easy as possible for you to get involved.

We welcome all contributions to this project via GitHub issues and pull requests.
Please follow these guidelines to make sure your contributions can be easily integrated into the projects.
As you start contributing to _EDS book_, don't forget that your ideas are more important than perfect pull requests. :green_heart:

If you have any questions that aren't discussed below, please let us know through one of the many ways to [get in touch](#get-in-touch).

## Table of contents

Been here before? Already know what you're looking for in this guide? Jump to the following sections:

- [Joining the community](#joining-the-community)
- [Inclusivity](#inclusivity)
- [Get in touch](#get-in-touch)
- [Contributing through GitHub](#contributing-through-github)
- [Writing in Markdown](#writing-in-markdown)
- [Where to start: issues](#where-to-start-issues)
- [Issue labels](#issue-labels)
- [Making a change with a pull request](#making-a-change-with-a-pull-request)
- [1. Comment on an existing issue or open a new issue referencing your addition](#1-comment-on-an-existing-issue-or-open-a-new-issue-referencing-your-addition)
- [2. Fork _EDS book_ repository to your profile](#2-forkgithub-fork-eds-book-repository-to-your-profile)
- [3. Make the changes you've discussed](#3-make-the-changes-youve-discussed)
- [4. Submit a pull request](#4-submit-a-pull-requestgithub-pullrequest)
- [Representing _EDS book_](#representing-eds-book)
- [Recognising Contributions](#recognising-contributions)

## Joining the community

_EDS book_ is a community-led and collaboratively developed project.
We, therefore, require that all our members and their contributions **adhere to our [Code of Conduct](CODE_OF_CONDUCT.md) (CoC)**.

Please familiarize yourself with our [CoC](CODE_OF_CONDUCT.md) that lists the expected behaviours.

## Inclusivity

_EDS book_ aims to be inclusive to people from all walks of life and to all research fields.

These intentions must be reflected in the contributions that we make to the project.

## Get in touch

There are many ways to get in touch with _EDS book_ team!

- GitHub [issues](https://github.com/alan-turing-institute/environmental-ds-book/issues) and [pull requests](https://github.com/alan-turing-institute/environmental-ds-book/pulls)
- 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](https://github.com/alan-turing-institute/environmental-ds-book/issues/new/choose)! (See our [Where to start: issues](#where-to-start-issues) section below.)
- For structured discussion and sustained engagement with the community members.
- Contact the maintainers of _EDS book_ project - Alejandro Coca-Castro - by email at [[e-mail]](mailto:[e-mail]) and/or Anne Fouilloux - by email at [[e-mail]](mailto:[e-mail]).

### Receiving Updates

- [@eds_book](https://twitter.com/eds_book) on Twitter and [fosstodon.org/@EDSbook](https://fosstodon.org/@EDSbook) in Mastodon
- Follow us for regular updates

### Coworking and Real-Time Collaboration

- **Bimonthly Collaboration Cafe:** We shared-out recent progress, achievements or events at _The Turing Way_ [Collaboration Cafes](https://the-turing-way.netlify.app/community-handbook/coworking/coworking-collabcafe.html). At least one of core EDS book members (as described in the [Ways of Working document](https://github.com/alan-turing-institute/environmental-ds-book/blob/master/ways_of_working.md)) will be attending the collaboration cafe to onboard or discuss relevant topics within _EDS book_ and _The Turing Way_ communities. Members of both communities are also welcome to join to [#environmental-sustainability](https://theturingway.slack.com/archives/C04RCMAEPUZ)) in _The Turing Way_ Slack, a dedicated channel for discussing broadly relevant topics aligned to Open Research in Environment & Sustainability.
- Shared notes with joining links: https://hackmd.io/@turingway/collaboration-cafe.
- **Monthly Co-working sessions:** Every Second Friday (16:00 - 17:00 London time). This is a synchronous collaborative space to either discuss your ideas or quietly work in an accountable space with _EDS book_ team members.
- Shared notes with joining links: https://hackmd.io/@eds-book/coworking-call/.

## Contributing through GitHub

[Git][git] is a really useful tool for version control.
[GitHub][github] sits on top of Git and supports collaborative and distributed working.

We know that it can be daunting to start using Git and GitHub if you haven't worked with them in the past, but _EDS book_ maintainers are here to help you figure out any of the jargon or confusing instructions you encounter! :green_heart:

In order to contribute via GitHub, you will need to set up a free account and sign in.
Here are some [instructions](https://help.github.com/articles/signing-up-for-a-new-github-account/) to help you get going.
Remember that you can ask us any questions you need to along the way.

## Writing in Markdown

GitHub has a helpful page on [getting started with writing and formatting on GitHub](https://help.github.com/articles/getting-started-with-writing-and-formatting-on-github).

Most of the writing that you will do will be in [Markdown][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.

Also when writing in Markdown, please [start each new sentence on a new line](https://the-turing-way.netlify.app/community-handbook/style.html#write-each-sentence-in-a-new-line-line-breaks).
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](https://help.github.com/en/articles/about-comparing-branches-in-pull-requests) review easier to read! :sparkles:

## Where to start: issues

Before you open a new issue, please check if any of our [open issues](https://github.com/alan-turing-institute/environmental-ds-book/issues) cover your idea already.
If you open a new issue, please follow our basic guidelines laid out in our [issue templates](https://github.com/alan-turing-institute/environmental-ds-book/issues/new/choose).
There are 5 issues templates to choose from.:
1. :bug: Bug Report ([preview here](https://github.com/alan-turing-institute/environmental-ds-book/issues/new?assignees=&labels=bug&projects=&template=bug-report.md&title=%5BBUG%5D)): With this template, create an issue report that can help others repair something that is currently broken.
2. :black_nib: Documentation Improvement ([preview here](https://github.com/alan-turing-institute/environmental-ds-book/issues/new?assignees=&labels=documentation&projects=&template=documentation-request.md&title=%5BDOC%5D)): This issue is to help us improve the documentation in the book or notebook repositories hosted in the [eds-book-gallery](https://github.com/eds-book-gallery) organisation. Alternatively you can just open a pull request with the suggested improvement.
3. :green_book: Notebook Idea ([preview here](https://github.com/alan-turing-institute/environmental-ds-book/issues/new?assignees=&labels=documentation&projects=&template=documentation-request.md&title=%5BDOC%5D)): Use this template for submitting a notebook idea. You can find further info of the scope of notebooks ideas within the [Publishing guidelines](book/publishing/guidelines.md).
4. :mag: PRE-REVIEW ([preview here](https://github.com/alan-turing-institute/environmental-ds-book/issues/new?assignees=&labels=prereview&projects=&template=prereview-template.md&title=%5BPRE+REVIEW%5D)): Editors-in-chiefs use this template for open a [PRE-REVIEW issue](book/publishing/guidelines/guidelines-eic.md#pre-review).
5. :eyes: REVIEW ([preview here](https://github.com/alan-turing-institute/environmental-ds-book/issues/new?assignees=&labels=review&projects=&template=review-template.md&title=%5BREVIEW%5D)): Editors-in-chiefs use this template for open a [REVIEW issue](book/publishing/guidelines/guidelines-eic.md#review).

## Making a change with a pull request

We appreciate all contributions to _EDS book_.
**THANK YOU** for helping us build this useful resource. :seedling:

All project management, conversations and questions related to _EDS book_ project happens here in [_EDS book_ repository](https://github.com/alan-turing-institute/environmental-ds-book).
This is also where you can contribute directly to writing or editing chapters of [the book](https://edsbook.org)!

The following steps are a guide to help you contribute in a way that will be easy for everyone to review and accept with ease :mortar_board:.

### 1. Comment on an [existing issue](https://github.com/alan-turing-institute/environmental-ds-book/issues) or open a new issue referencing your addition

This allows other members of _EDS book_ 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](https://www.igvita.com/2011/12/19/dont-push-your-pull-requests/) is a nice explanation of why putting this work in upfront is so useful to everyone involved.

### 2. [Fork][github-fork] _EDS book_ repository

This is now your own unique copy of _EDS book_.
Changes here won't affect anyone else's work, so it's a safe space to explore edits to the code!

Make sure to [keep your fork up to date][github-syncfork] with the main repository, otherwise, you can end up with lots of dreaded [merge conflicts][github-mergeconflicts].
If you prefer working in the browser, [these instructions](https://github.com/KirstieJane/STEMMRoleModels/wiki/Syncing-your-fork-to-the-original-repository-via-the-browser) describe how to sync your fork to the original repository via GitHub.

### 3. Make the changes you've discussed

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 pull request.
[Help them help you.][jerry-maguire] :wink:

While making your changes, commit often and write good, detailed commit messages.
[This blog](https://chris.beams.io/posts/git-commit/) 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.
A good rule of thumb is to push up to GitHub when you _do_ have passing tests then the continuous integration (CI) has a good chance of passing everything. 😸

If you feel tempted to "branch out" then please make a [new branch][github-branches] and a [new issue][eds-book-issues] to go with it. [This blog](https://nvie.com/posts/a-successful-git-branching-model/) details the different Git branching models.

Please do not re-write history!
That is, please do not use the [rebase](https://help.github.com/en/articles/about-git-rebase) command to edit previous commit messages, combine multiple commits into one, or delete or revert commits that are no longer necessary.

Are you new to Git and GitHub or just want a detailed guide on getting started with version control? Check out our [Version Control chapter](https://the-turing-way.netlify.com/version_control/version_control.html) in _The Turing Way_ Book!

### 4. Submit a [pull request][github-pullrequest]

We encourage you to open a pull request as early in your contributing process as possible.
This allows everyone to see what is currently being worked on.
It also provides you, the contributor, feedback in real-time from both the community and the continuous integration as you make commits (which will help prevent stuff from breaking).

When you are ready to submit a pull request, you will automatically see the [Pull Request Template](https://github.com/alan-turing-institute/environmental-ds-book/blob/master/.github/pull_request_template.md) contents in the pull request body.
It asks you to:

- Describe the problem you're trying to fix in the pull request, reference any related issue and use fixes/close to automatically close them, if pertinent.
- List of changes proposed in the pull request.
- Describe what the reviewer should concentrate their feedback on.
- Acknowledging contributors.

By filling out the "_Lorem ipsum_" sections of the pull request template with as much detail as possible, you will make it really easy for someone to review your contribution!

If you have opened the pull request early and know that its contents are not ready for review or to be merged, add "[WIP]" at the start of the pull request title, which stands for "Work in Progress".
When you are happy with it and are happy for it to be merged into the main repository, change the "[WIP]" in the title of the pull request to "[Ready for review]".

A member of _EDS book_ team will then review your changes to confirm that they can be merged into the main repository.
A [review][github-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.

You can update your [fork][github-fork] of _EDS book_ [repository][eds-book-repo] and the pull request will automatically update with those changes.
You don't need to submit a new pull request when you make a change in response to a review.

You can also submit pull requests to other contributors' branches!
Do you see an [open pull request](https://github.com/alan-turing-institute/environmental-ds-book/pulls) that you find interesting and want to contribute to?
Simply make your edits on their files and open a pull request to their branch!

What happens if the continuous integration (CI) fails (for example, if the pull request notifies you that "Some checks were not successful")?
The CI could fail for a number of reasons.
At the bottom of the pull request, where it says whether your build passed or failed, you can click “Details” next to the test, which takes you to a CI run log site.
If you have the write access to the repo, you can view the log or rerun the checks by clicking the “Restart build” button in the top right.
You can learn more about CI in the [Continuous Integration chapter](https://the-turing-way.netlify.app/reproducible-research/ci.html)!

GitHub has a [nice introduction][github-flow] to the pull request workflow, but please [get in touch](#get-in-touch) if you have any questions or ideas :bulb:.

## Local development

You can build and host the book website locally. The steps are:

### To build book locally

1. Install the required software to build the book, optionally in a [virtual environment](https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments):

   pip install -r book/requirements.txt

2. You can now build or refresh the book using:

   cd ./book/website
   jupyter-book build .

## Representing _EDS book_

We would LOVE people to give talks about the project or represent _The Turing Way_ in other ways!
We have created a [promotion pack](https://github.com/alan-turing-institute/environmental-ds-book/tree/master/communications/promotion-pack) for you to reuse.
You will find useful details about the project, a list of frequently asked questions, slide decks, and contact details.

If you would like to represent the project in your network, please open an issue and ping @acocac, @annefou so that they can do their best to support you.

We suggest to archive presentations in Zenodo and tag [Environmental Data Science book](https://zenodo.org/communities/the-environmental-ds-community) community. This will make more visible the presentation to wider Open Science network.

## Recognising Contributions

We welcome and recognise all kinds of contributions, from fixing small errors, to developing documentation, maintaining the project infrastructure, writing chapters or reviewing existing resources.

In the [contributing chapter](book/preamble/contribute.md), you can read how your contributions will be acknowledged and recorded in _EDS book_.
_EDS book_ follows the [all-contributors][all-contributors] specifications.
The all-contributors bot usage is described [here](https://allcontributors.org/docs/en/bot/usage).
You can see a list of current contributors [here](https://github.com/the-turing-way/the-turing-way/blob/main/contributors.md). 😍

To add yourself or someone else as a contributor, comment on the relevant Issue or Pull Request with the following:

@all-contributors please add <username> for <contributions>

You can see the [Emoji Key (Contribution Types Reference)](https://allcontributors.org/docs/en/emoji-key) for a list of valid `<contribution>` types and examples of how we've run this command in [this issue](https://github.com/alan-turing-institute/environmental-ds-book/issues/29).
The bot will then create a Pull Request to add the contributor and reply with the pull request details.

**PLEASE NOTE: Only one contributor can be added with the bot at a time!**
Add each contributor in turn, merge the pull request and delete the branch (`all-contributors/add-<username>`) before adding another one.
Otherwise, you can end up with dreaded [merge conflicts][github-mergeconflicts].
Therefore, please check the open pull requests first to make sure there aren't any [open requests from the bot](https://github.com/alan-turing-institute/environmental-ds-book/pulls/app%2Fallcontributors) before adding another.

What happens if you accidentally run the bot before the previous run was merged and you got those pesky merge conflicts?
(Don't feel bad, we have all done it! 🙈)
Simply close the pull request and delete the branch (`all-contributors/add-<username>`).
If you are unable to do this for any reason, please let us know by opening an issue, and _EDS book_ team members will be very happy to help!

Finally, don't forget to add yourself to the list of contributors [here](https://github.com/alan-turing-institute/environmental-ds-book/blob/main/contributors.md)!

---

_These Contributing Guidelines have been adapted from [The Turing Way Contributing Guidelines](https://github.com/the-turing-way/the-turing-way/blob/main/CONTRIBUTING.md) (License: CC BY 4.0) which were originally sourced from [the BIDS Starter Kit](https://github.com/bids-standard/bids-starter-kit)! (License: CC-BY)_

[eds-book-repo]: https://github.com/alan-turing-institute/environmental-ds-book/
[eds-book-issues]: https://github.com/alan-turing-institute/environmental-ds-book/issues
[git]: https://git-scm.com
[github]: https://github.com
[github-branches]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository
[github-fork]: https://help.github.com/articles/fork-a-repo
[github-flow]: https://guides.github.com/introduction/flow
[github-mergeconflicts]: https://help.github.com/articles/about-merge-conflicts
[github-pullrequest]: https://help.github.com/articles/creating-a-pull-request
[github-review]: https://help.github.com/articles/about-pull-request-reviews
[github-syncfork]: https://help.github.com/articles/syncing-a-fork
[markdown]: https://daringfireball.net/projects/markdown
[rick-roll]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
[jerry-maguire]: https://media.giphy.com/media/uRb2p09vY8lEs/giphy.gif
[all-contributors]: https://github.com/kentcdodds/all-contributors#emoji-key