🎉🎈🍰 Welcome to the Turing Way repository! 🍰🎈🎉
💫🐥☀️ We're so excited you're here and want to contribute. ☀️🐥💫
We want to ensure that every user and contributor feels welcome and included to the Turing Way community.
We hope that this guideline 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 in 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.
Been here before? Already know what you're looking for in this guide? Jump to the following sections:
- Joining the community
- Inclusivity
- Get in touch
- Contributing through GitHub
- Writing in Markdown
- Where to start: issues
- Making a change with a pull request
- The process of writing chapters
- Style Guide
- Recognising Contributions
The Turing Way is a community-oriented and -led project. We therefore require that all our members and their contributions adhere to our Code of Conduct. Please familiarize yourself with the Code of Conduct that lists the expected behaviours and our reporting guidelines.
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 Code of Conduct, we encourage intentional inclusive actions from contributors to The Turing Way. Here are a few examples of such actions:
- Refer to "open research" rather than only "open science" so that we do not exclude members of the humanities and social sciences from our community.
- Make sure colour palettes are accessible to colour-blind readers and contributors. Here's a useful blog post on tips for designing scientific figures for color blind readers by Luk at Somersault 1824.
There are many ways to get in touch with the Turing Way team!
- Ping us in our gitter channel.
- This is our preferred method of open communication and discussion! We'd love for you to swing by to say hello.
- Join the discussion in our issues and pull requests.
- Can't find your idea being discussed anywhere? Open a new issue! (See our Where to start: issues section below.)
- Subscribe to our mailing list with which we send monthly project updates.
- Follow @turingway on Twitter.
- You can contact the Project Lead of The Turing Way project - Kirstie Whitaker - by email at [email protected].
- You can contact the Community Manager of The Turing Way project - Malvika Sharan - by email at [email protected].
- You can also contact other members of the Turing Way through their preferred ways of communication here.
Git is a really useful tool for version control. 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 the Turing Way maintainers are 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 a free account and sign in. Here are some instructions to help you get going. Remember that you can ask us any questions you need to along the way.
GitHub has a helpful page on getting started with writing and formatting on GitHub.
Most of the writing that you'll 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 ([link](https://https://youtu.be/dQw4w9WgXcQ)) to another webpage.
Also when writing in Markdown, please start each new sentence on a new line. While this formats in the same way as if the new line wasn't included, 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 covers your idea already. If you open a new issue, please follow our basic guidelines laid out in our issue template. The issue template will automatically be rendered in the comment section of the new issue page, so all you need to do is edit the "Lorem ipsum" sections.
The list of labels for current issues can be found here and includes:
-
These issues contain a task that a member of the team has determined we need additional help with.
If you feel that you can contribute to one of these issues, we especially encourage you to do so!
-
These issues contain a question that you'd like to have answered.
There are lots of ways to ask questions but opening an issue is a great way to start a conversation and get your answer.
-
These issues are particularly appropriate if it is your first contribution to the Turing Way, or to GitHub overall.
If you're not sure about how to go about contributing, these are good places to start. You'll be mentored through the process by the maintainers team. If you're a seasoned contributor, please select a different issue to work from and keep these available for the newer and potentially more anxious team members.
-
These issues are suggesting new features that can be added to the project.
If you want to ask for something new, please try to make sure that your request is distinct from any others that are already in the queue (or part of the Turing Way). If you find one that's similar but there are subtle differences please reference the other enhancement in your issue.
-
These issues relate to building and supporting the Turing Way community.
This is all about collaborating, so please let us know how we can best support you as a community member.
-
These issues are reporting a problem or a mistake in the project.
The more details you can provide the better! If you know how to fix the bug, please open an issue first and then submit a pull request ✨
-
These issues cover everything around the process of writing the book.
-
These issues help us organise our workshops.
-
We like to model best practice, so the Turing Way itself is managed through these issues. These issues help us to coordinate some logistics.
-
Everything related to building a BinderHub
-
These issues discuss tools we use for collaboration
If you feel that we should try new tools or some aspects of the collaboration could be improved by using tools, please let us know.
-
These issues are mainly for the attention of core project members to plan travel to face to face meetings
-
These issues discuss how we as a project interact with other initiatives.
We appreciate all contributions to the Turing Way. THANK YOU for helping us build this useful resource. ✨🌟💫
All project management, conversations and questions related to the Turing Way project happens here in the Turing Way repository. This is also where you can contribute directly to writing or editing chapters of the book!
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 😎.
1. Comment on an existing issue or open a new issue referencing your addition
This allows other members of the Turing Way 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.
Remember, if you open a new issue, please follow our basic guidelines laid out in our issue template. The issue template will automatically be rendered in the comment section of the new issue page so all you need to do is edit the "Lorem ipsum" sections.
2. Fork the Turing Way repository to your profile
This is now your own unique copy of the Turing Way. 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 with the master repository, otherwise you can end up with lots of dreaded merge conflicts. If you prefer working in the browser, these instructions describe how to sync your fork to the original repository via GitHub.
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 whomever is reviewing your pull request. Help them help you. 😉
While making your changes, commit often and write good, 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. 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 and a new issue to go with it. This blog details the different Git branching models.
Please do not re-write history! That is, please do not use the 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 in the Turing Way Book!
4. Submit a pull request
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 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.
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 the Turing Way team 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.
You can update your fork of the Turing Way repository 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 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 the Travis page. You can view the log or rerun the checks if you have write access to the repo by clicking the “Restart build” button in the top right (you must be logged in to Travis CI with your GitHub account see the “Restart build” button). You can learn more about Travis in the Continuous Integration chapter of the book!
GitHub has a nice introduction to the pull request workflow, but please get in touch if you have any questions 🎈.
- Fork the repository from the alan turing version if you have not done so already.
- On the alan turing version create a branch with the same name as the chapter to be written.
- On your fork create a branch with the same name and create a markdown file on it.
- Copy the chapter template in the templates directory into the markdown file, and commit.
- Make a pull request to the turing way version of the chapter branch. The title of this request should have the form "[WIP] Write Chapter_name chapter". WIP indicates the chapter is a Work In Progress and not yet ready for review.
- On your branch add material to the chapter and commit. The goal of this project is to collate and build on the many good resources already available about good practise in data science. As such this material should primarily be drawn from outside sources. Note the link and (if available) license of the source.
- Once a significant amount of material has been amassed, work (preferably with others) to develop a chapter outline.
- Edit the amassed material into a coherent chapter, adding more material if gaps become apparent.
- Edit the chapter for style.
- Once the first draft of the chapter is complete change [WIP] in the pull request title to [Ready for review].
- Add a comment on the pull request indicating that this chapter is ready for high level review, i.e discussion of changes of scale of a paragraph or larger such as adding material and restructuring sections.
- Discuss and make these high level changes on this pull request. Once this is complete merge the chapter into the alan turing intitute's version of the chapter branch.
- Make another pull request from your fork's version of the branch to the alan turing institute's version of the branch. Title this "[Ready for review] Chapter_name chapter- low level reviews".
- Discuss and make low level changes to the chapter on this pull request, such as rewording sentences, typos and the like.
- This division of the pull requests into high and low level changes stops discussion threads becoming unmanagably long.
- Once this is complete merge the pull request into the alan turing intitute's version of the chapter branch.
- Merge the alan turing intitute's version of the chapter branch into the alan turing master branch.
- DO not delete the branch as the chapter may continue to undergo improvement and development in the future.
You can host the book website locally. The steps are:
-
Install docker: see Reproducible Environments for discussion of docker and containers.
-
Make sure you have docker-compose installed: compose installation instructions
-
The website can then be started using:
cd book/website docker-compose upThis will install all ruby requirements and make the site available at
http://0.0.0.0:4000/introduction/introduction.You can refresh your build using:
jupyter-book build .
To ensure all text can be read easily by all (including screen readers and non-native english speakers), follow Gov.uk guidance on e.g., i.e., and etc. (1) That is, do not use them:
eg can sometimes be read aloud as ‘egg’ by screen reading software. Instead use ‘for example’ or ‘such as’ or ‘like’ or ‘including’ - whichever works best in the specific context.
etc can usually be avoided. Try using ‘for example’ or ‘such as’ or ‘like’ or ‘including’. Never use etc at the end of a list starting with these words.
ie - used to clarify a sentence - is not always well understood. Try (re)writing sentences to avoid the need to use it. If that is not possible, use an alternative such as ‘meaning’ or ‘that is’.
When writing all sentences should go on a new line. This will make no difference to how the text is displayed, there will still be paragraphs, but it will mean that any pull requests will be easier to check; the changes will be on a single line instead of somewhere in a paragraph. Consider the example below.
Today you are you, that is truer than true. There is no one alive who is youer than you. - Dr Seuss
A pull request on this correcting it to have a ‘.’ after Dr would show as a change to the whole paragraph. Contrast this with the next example which will be displayed online in the exact same way, but would see a change to a single line.
Today you are you, that is truer than true.
There is no one alive who is youer than you.
- Dr Seuss
The Turing Way book is intended to be only lightly opinionated.
Whilst more opinionated content is allowed, such content should be clearly marked.
The best way to do this is by displaying it in a quote box.
This can be done by either prefixing every line with the greater than symbol >.
Note, that the formatting will be retained, so we can split each sentence to a new line as recommended before.
> I will not eat them in a house,
> i will not eat them with a mouse,
> i will not eat them in a box i will not eat them with a fox,
> i will not eat them here of there i will not eat them anywhere,
> I do not like green eggs and ham i do not like them sam i am
To make things look cleaner, it is advised that all figures be encapsulated in a table with a caption. This can be done simply as:
|  |
| ------------------------------------------------------------------------------------ |
| Try them, try them, and you may! Try them and you may, I say. |
Figures should be added to the book/content/figures directory.
The Travis continuous-integration tests will check for formatting errors using prettier.io. You can see a list of all files with style issues by looking at the Travis build logs, for example:
Checking formatting...
book/content/introduction/introduction.md
book/content/open_research/open_research.md
Code style issues found in the above file(s). Forgot to run Prettier?
The command "prettier --check ./book/content/**/*.md" exited with 1.
Optional: If you would like to apply auto-formatting when editing locally, we recommend pre-commit. To get started, run the following from your shell:
pip install pre-commit
pre-commit install
Each time you attempt to commit a change with git, pre-commit will run the prettier auto-formatter and automagically fix any style issues.
We maintain a centralised bibtex file containing all references. The file is located at
./book/website/_bibliography/references.bib
You can edit references locally using a method from the following:
- Edit
references.bibdirectly using a text editor - Edit
references.bibdirectly using a managing program such as JabRef (linux, windows, macOS) or BibDesk (macOS)
To include a citation in your content, follow the guide for jekyll-scholar. The key concepts are:
- Include a reference using
{% cite CITEKEY %}, whereCITEKEYis the corresponding citation key inreferences.bib - Add a bibliography entry to your section using
{% bibliography --cited %}
For example, say we have an entry in the references.bib file as:
@article{Kuula2010archiving,
Author = {Kuula, Arja},
Date-Added = {2019-05-28 17:47:46 +0100},
Date-Modified = {2019-05-30 8:57:26 am +0100},
Journal = {IASSIST Quarterly},
Number = {3-4},
Pages = {35},
Title = {Methodological and Ethical Dilemmas of Archiving Qualitative Data},
Url = {http://www.iassistdata.org/sites/default/files/iqvol34_35_kuula.pdf},
Volume = {34},
Year = {2010}}
We could cite this article in the book using {% cite Kuula2010archiving %}.
We recommend using the following structure for citation keys:
AuthorYYYYword
where
Authoris the surname of the first author (Kuulaabove)YYYYis the year (2010above)wordis the first meaningful word in the title (archivingabove). Note, this is subjective – choose a name that makes it easy to remember the reference when you see the citation key.
Links between different pages within the book (e.g. Open Research and Version Control) should be added as relative links. Relative links are added by inserting the file path in brackets, ( ), where you would usually add a URL as demonstrated below:
> [Experience with version control](/version_control/version_control)
> The [next section](../03/definitions.html) of this chapter
The path you add starts from the content folder in this github repository.
Note the difference between starting your path with /, which means it will start from the content folder vs starting from the location of the file you're writing in.
A nice easy way to find absolute path can be found by looking at the page you would like to link to (for example, https://the-turing-way.netlify.com/testing/testing.html) and then taking everything after https://the-turing-way.netlify.com. Please note that you do not need to include the file extension, for example .html, in your relative path.
The Turing Way follows the all-contributors specification, so we welcome and recognise all contributions from documentation to testing to writing chapters. You can see a list of current contributors here. 😍
The all-contributors bot usage is described here. 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.
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.
Therefore, please check the open pull requests first to make sure there aren't any open requests from the bot 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 in the Gitter channel or by opening an issue, and a Turing Way team member will be very happy to help!
Finally, don't forget to add yourself to the list of contributors here!
These Contributing Guidelines have been adapted from the Contributing Guidelines of the BIDS Starter Kit! (License: CC-BY)