Welcome! We're excited about your interest in contributing to this resources, which we will refer to in this document as intro_python_chemists as that is the name of the Github Repo.
These guidelines are designed to make it as easy as possible to get involved. If you have any questions that aren't discussed below, please let us know by opening an issue!
Before you start you'll need to set up a free GitHub account and sign in. Here are some instructions.
Already know what you're looking for in this guide? Use the TOC to the right to navigate this page!
This is a young project maintained mainly by Andrew R. McCluskey and we're excited to have you join! Most of our discussions will take place on open issues.
As a reminder, we expect all contributors to this book to adhere to the Code of Conduct in these conversations.
git is a really useful tool for version control. GitHub sits on top of git and supports collaborative and distributed working.
You'll use Markdown to chat in issues and pull requests on GitHub.
You can think of Markdown as a few little symbols around your text that will allow GitHub to render the text with formatting.
For example you could write words as bold (**bold**) or in italics (*italics*)
GitHub has a helpful page on getting started with writing and formatting Markdown on GitHub.
Every project on GitHub uses issues slightly differently.
The following outlines how the intro_python_chemists developers think about these tools.
Issues are individual pieces of work that need to be completed to move the project forwards. A general guideline: if you find yourself tempted to write a great big issue that is difficult to describe as one unit of work, please consider splitting it into two or more issues.
Projects are used to describe the broader picture of the intro_python_chemists project.
More information about the overall project plan can be found on the Github projects page.
In this book we prioritise readibility and understandability of code over everything else. Therefore, the code herein will not necessarily adhere to PEP8 or any other standard, in particular if it sacrifices the educational utility of the material. All issues opened that are based purely on standard adherence will be closed without considering. However, we are open to issues and pull requests that discuss/improve coding style if the focus is on making the code clearer for the learner.
The most likely place that you will contribute is in the content of the book.
We suggest that you read the style guide before you start on your content.
Details of the planned content of each chapter can be found in the toc.yml, so we suggest that you have a look at what sections there are an fill in one of the gaps.
If you would like to contribute something that is not mentioned in the Table of Contents, then please open an issue and the community can discuss the contribution.
We try to follow a relatively standard series of steps for someone to offer a contribution to the material:
1. Comment on an existing issue or open a new issue referencing your addition.
This allows other members of the development 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 up front is so useful to everyone involved.
2. Fork the jupyter-book repository to your profile.
This is now your own unique copy of intro_python_chemist.
Changes here won't effect 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 with the master repository.
3. Make the changes you've discussed.
Try to keep the changes focused. We've found that working on a new branch makes it easier to keep your changes targeted.
Once you have made changes in a Jupyter Notebook file or Markdown file, and you are happy with them, commit them!
4. Submit a pull request.
A member of the development team will review your changes to confirm that they can be merged into the main code base. When opening the pull request, we ask that you follow some specific conventions. We outline these below.
Pull requests should be submitted early and often!
If your pull request is not yet ready to be merged, please open your pull request as a draft. More information about doing this is available in GitHub's documentation. This tells the development team that your pull request is a "work-in-progress", and that you plan to continue working on it.
When your pull request is Ready for Review, you can select this option on the PR's page, and a project maintainer will review your proposed changes.
You're awesome.
— Based on contributing guidelines from the STEMMRoleModels project.