Contributing to The Turing Way

🎉🎈🍰 Welcome to The Turing Way! 🍰🎈🎉

💫 We’re excited that you’re here and want to contribute. 💫

We want to ensure that every user and contributor feels welcome, included and supported to participate in The Turing Way 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 The Turing Way, don’t forget that your ideas are more important than perfect pull requests. ❤️

If you have any questions that aren’t discussed below, please let us know through one of the many ways to get in touch.

Code of Conduct¶

The Turing Way is a community-led and collaboratively developed project. We, therefore, require that all our members and their contributions adhere to our CoC. Please familiarize yourself with our CoC that lists the expected behaviours.

Inclusivity¶

The Turing Way 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.

In addition to the CoC, we encourage intentional, inclusive actions from contributors to The Turing Way. For example, you should:

Use respectful, gender-neutral and inclusive language.
Aim to include perspectives of researchers from different research backgrounds.
Make sure that the colour palettes are accessible to colour-blind readers and contributors. See the blog post Designing Scientific Figures for Colour Blindness for an example of how somebody improved one of their diagrams, including links to recommended colour palettes and a colour-blindness simulator.

Join the Community¶

There are many ways to engage with the community! We maintain a set of useful resources and announcements at the-turing-way.org.

Slack¶

We use Slack for more informal and rapid communication. There are channels for working groups, asking for support, and community discussion. There are also off-topic channels for socialising with other community members. Slack is also a good place to receive notifications for upcoming events.

You can sign up to our newsletter to receive monthly project updates.

GitHub¶

The Turing Way is developed on GitHub. We use GitHub discussion, issues and pull requests to organise ideas and contributions. Collaborating on GitHub and Making Changes with a Pull Request explain how to use these features.

Coworking and Real-Time Collaboration¶

The Turing Way hosts synchronous events using video conferencing for focused collaboration. These include working group meetings, regular collaboration cafes and week-long Book Dash sprint events. These events can be found on the community calendar.

Email¶

You can also contact the Community Management Working Group and the Steering Committee by emailing theturingway@gmail.com.

Collaborating on GitHub¶

Git is a really useful tool for version control. GitHub sits on top of Git and supports collaborative and distributed working. It can be daunting to start using Git and GitHub if you haven’t worked with them in the past. We are here to help if you encounter problems! ❤️

In order to contribute via GitHub, you’ll need to create a free account. Read the GitHub documentation for instructions.

Issues and Discussions¶

Look through open items first; join discussions, collaborate on an ongoing tasks and exchange your thoughts with others. If you can’t find an open item related to your idea, you can open a new one. Open and discussion if you have a question, or an idea to talk about with the community. Open an issue if you have a specific task like fixing a bug or editing part of the book. Our issue templates guide you to add the important information.

Good First Issues¶

We mark issues suitable for first contributions with the good first issue label.

Good First Pull Requests¶

If you would like opportunities to review others’ contributions, we mark good pull requests for new reviewers with the good first PR review label.

Writing Markdown¶

The Turing Way is written almost entirely in Markdown. In particular, it is written in a flavour of Markdown called MyST Markdown.

The Style Guide section of the Community Handbook explains our conventions and recommendations for writing Markdown. You can also read the Authoring section of the MyST Markdown Guide for the complete set of features and Syntax.

Making Changes with a Pull Request¶

Changes to the book are always made through pull requests. We encourage all contributors to work on their own fork of the repository. Pull requests should be self-contained and as small as possible.

Pull request should be marked as drafts until there are ready for review.

We follow the GitHub flow workflow:

Create a feature branch on your fork
Commit changes
Open a pull request to The Turing Way’s repository

Open a draft pull request if the work is still in progress
Open a pull request if you feel the work is ready for review

Iterate on changes in response to CI and reviewer comments
Merge when all issues are addressed and changes are approved

Best Practice¶

Here are some tips for best practice working with git:

Keep your fork up to date with the main repository
Try to keep changes focused. If you submit many changes at once it will be much more difficult to review.
Make small commits often.
Write good commit messages.
Do not re-write history!
Open draft pull requests soon, to get early feedback.

Chapter Templates¶

If you are writing a new chapter, make use of the chapter template.

Local development¶

You can build the book locally during development. This is the quickest way to see how you changes affect the book. The steps are described in Build the Book Locally.

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. The community handbook explains how contributions will be acknowledged and recorded in The Turing Way.

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) for a list of valid <contribution> types and examples of how we’ve run this command in this issue. The bot will then create a Pull Request to add the contributor and reply with the pull request details.

Finally, don’t forget to add yourself to the list of contributors!