By contributing to this project, you agree that we may redistribute your work under the Creative Commons Attribution 4.0 International Public License (CC BY 4.0) as specified by the project’s licence file.
When contributing to this project you are expected to abide by The Carpentries Code of Conduct.
To get in touch with the lesson maintainers, send an email to [email protected].
You will need a GitHub account to contribute to this project, and can do so in a variety of ways, including:
- Reporting problems and suggesting changes to the lesson material or project documentation (e.g. README, contributing guidelines, etc.) via project issues,
- Commenting, voting and participating in discussions on existing issues or proposed changes and pull requests,
- Contributing changes to the lesson material via pull requests.
The source files for the lesson (as well as most of the lesson project files) are written in Markdown. Markdown is quite a flexible markup language, and we suggest to follow some guidelines on Markdown format to make editing these files easier.
Regular prose should not exceed 100 characters per line. This helps avoid line wrapping in editors which can make comparing changes in the source code difficult.
Please attempt to follow semantic line breaks when editing or adding prose in the explanatory portions of the lesson. Don’t worry about this when editing code examples. Briefly, semantic line breaks means:
- Create a newline after a sentence (punctuated with a ‘.’, ‘!’, or ‘?’)
- Create a newline after an independent clause (punctuated with comma, semi-colon, colon or em dash)
- Create a newline to satisfy line length guides (100 characters in our case).
The lesson is developed using The Carpentries Jekyll lesson template and you should be familiar with it before making bigger contributions (as you will likely need to install and render your branch of the lesson locally to test your proposed changes). You can check out the lesson example guide and the corresponding lesson template source repository to familiarise yourself with the lesson template and file structure before making a pull request with substantial changes.
If you notice a problem with the lesson material or want to suggest a change or start a conversation on a lesson-related topic - you can do so by creating a new issue on the project’s issues page. Before opening a new issue, check the list of opened issues first to see if there is already an existing report/discussion on the same subject. If so, consider adding your thoughts to the existing issue instead of starting a new one.
While we welcome suggestions on how to extend the material, due to its size we may not be able to accommodate all such requests. You should, however, feel free to create your own fork of the material and make any requested changes there and create a pull request to bring your changes back into the main material to be considered by the lesson maintainers.
We welcome people to comment and vote on any issues, discussions or pull requests that they feel are important - this is an opportunity to explain your point of view and discuss why certain changes are needed.
Voting is done by leaving a reaction (👍 for +1, 👎 for -1) on an issue or pull request. Votes on issues may be used when prioritising work, and votes on pull requests may be taken into account by the project maintainers when deciding whether to accept it.
Changes to the lesson can only be done via pull requests from branches of the material:
- We welcome pull requests that address identified and reported issues/problems with the lesson, e.g. look for issues labelled “help wanted” or “good first issue” (for novice contributors).
- Try to group suggested changes into pull requests logically, e.g. if you are fixing a number of typos in the lesson we suggest grouping them together in a single pull request.
- Pull requests that add a lot of new material or a new episode to the lesson without discussing this first with the lesson maintainers are discouraged.
- Before starting the work, make sure there is a related issue open (so you can reference it in your pull request and use it for discussions). You can also put a comment on the relevant issue saying that you intend to address the issue so that any duplication of effort is avoided.
Small changes can be made directly using the GitHub user interface. Simply open the relevant file on the gh-pages branch, click the pencil icon to edit, make your change, and click the "Propose changes" button - GitHub will automatically create a fork (a separate copy of the lesson repository under your GitHub account), a feature branch from the gh-pages branch and a pull request for you.
If you are not making a change via the GitHub’s interface - you will have to manually create a fork from the lesson repository and a feature branch (to contain your changes) from the gh-pages branch.
If you are working locally on your machine, make sure that your local feature branch is pushed to your remote fork on GitHub. From the GitHub interface of your fork, select your feature branch, click the 'Pull Request' button and fill out the pull request form. In the description/comment section if the form, make sure to include:
- a brief summary of what changes were made
- why the changes were made, with links to any relevant issues or discussions
Your pull request should trigger a notification for the repository’s maintainers, and a member of the team will review your pull request in a timely manner. Check in from time to time, or wait for notifications of any reviewer comments or build failures.
If you need to make additional code changes (e.g. in response to reviewers’ comments), just push them to your feature branch on your fork and GitHub will update the open pull request automatically.
We maintain a list of contributors to this project under the AUTHORS file in the project root. If you make a pull request that gets accepted and merged, or contribute significantly to a discussion around one of the issues in the project, and would like to be recognised on this list - please append your name, email address and affiliation to the end of this file and create a new pull request with these changes.
Thank you for considering contributing to this project!