Skip to content

Latest commit

 

History

History
472 lines (332 loc) · 39.3 KB

CONTRIBUTING.md

File metadata and controls

472 lines (332 loc) · 39.3 KB
Raw

Contributing to The Turing Way

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

💫🐥☀️ 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.

Table of contents

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

Joining the community

The Turing Way is a community-led and collaboratively developed project. We, therefore, require that all our members and their contributions adhere to our Code of Conduct (CoC). Please familiarize yourself with our CoC that lists the expected behaviours. We have also provided details for CoC reporting and enforcement, which can be read in our Community Handbook.

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. Here are a few examples of such actions:

  • use respectful, gender-neutral and inclusive language (learn more about inclusive writing on page 22 of University of Leicester Study Skills pdf, also available as a zipped html).
  • aim to include perspectives of researchers from different research backgrounds such as science, humanities and social sciences by not limiting the scope to only scientific domains.
  • make sure that the colour palettes are accessible to colour-blind readers and contributors. See the blogpost 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.

Get in touch

There are many ways to get in touch with The Turing Way team!

  • GitHub issues and pull requests
    • 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! (See our Where to start: issues section below.)
  • Slack Channel
    • For structured discussion and sustained engagement with the community members.
    • We will also provide notifications on upcoming events and share useful resources on Slack.
    • You can also ping us on Gitter channel (open source option).
  • Contact the Community Manager of The Turing Way project – Anne Lee Steele – by email at asteele@turing.ac.uk
  • Contact the co-leads of The Turing Way project - Kirstie Whitaker - by email at kwhitaker@turing.ac.uk and Malvika Sharan - by email at masharan@turing.ac.uk.

Receiving Updates

  • @turingway on Twitter
    • Follow us for regular updates
  • Our mailing list: Receive monthly project updates in a newsletter
  • Fireside Chat Series: Every month, The Turing Way Fireside chat will feature experts, champions and their projects from across different international communities in reproducibility, open research, ethics, collaboration and everything in between. This will be an incredible opportunity for catalysing cross-community collaboration and knowledge sharing.
  • Useful links: other links to our resources along with announcements are shared via this HackMD: hackmd.io/@turingway/demo-intro

Coworking and Real-Time Collaboration

Contributing through GitHub

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.

Writing in Markdown

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://youtu.be/dQw4w9WgXcQ)) to another webpage.

Also when writing in Markdown, please start each new sentence on a new line. 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 review easier to read! ✨

Where to start: issues

Before you open a new issue, please check if any of our open issues cover your idea already. If you open a new issue, please follow our basic guidelines laid out in our issue templates. There are 3 issues templates to choose from.:

  1. New Chapter Template (preview here): This issue is a place to discuss matters relating to writing a new chapter on a new topic or adding a subchapter in an already existing chapter.
  2. General (preview here): Use this template for a general issue related to the book, community, process or ideas.
  3. Bug Report (preview here): With this template, create an issue report that can help others repair something that is currently broken. This can be used for reporting errors like typos and broken links. 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.

Issue labels

The list of labels for current issues can be found here and includes:

  • approval-request When a bug or minor changes have been made, contributors can label their PR along with "bug fixed".

  • binderhub These issues relate to documentation and resources around building a BinderHub.

  • book-build These issues are related to the build of the book using Jupyter-book. They are also related to the-turing-way book repo.

  • book-dash-feb20 These are to be used on issues and PR during/for the book dash in Feb 2020.

  • book-dash-ldn19 These are issues related to contributions made during the London Book Dash in 2019.

  • book-dash-mcr19 These are issues related to contributions made during the Manchester Book Dash in 2019.

  • Bug 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 ✨

  • bug-fixed These are bugs that have been fixed and only need approval.

  • collaboration-book These issues relate to the content of the collaboration book.

  • Comms These issues discuss how we as a project interact with other initiatives.

  • communication-book These issues relate to the content of the communication book.

  • Community 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.

  • conflicting-file-error These issues mark issues and pull requests with conflicting files and errors.

  • dependencies These issues relate to pull requests that update a dependency file.

  • Enhancement 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.

  • ethics-book These issues relate to the content of the ethics book.

  • events These issues relate to coordinating workshops, book dashes and any other events.

  • good-first-issue 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.

  • help-wanted 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!

  • idea-for-discussion These issues can be used for inviting discussion from collaborators or community in general.

  • newsletter These issues contain items that can be added to the newsletter.

  • outreach These issues relate to topics to reach out to the community.

  • good-first-PR-review These pull requests are for the new members of The Turing Way community who want to start with reviewing and approving some simple pull requests.

If you are a new member of The Turing Way and are looking for opportunities to start as a reviewer of contributions made on our Github repository, these pull requests are a great starting point for you. Issues like small modifications, typo errors and minor bug fixes are resolved by these PRs which are easy to review as a beginner.

  • pr-draft These issues relate to draft pull requests.

  • pr-merged These issues relate to pull requests that have been merged.

  • pr-partially-approved These issues relate to pull requests that have been partially approved.

  • pr-reviewed-approved These issues relate to pull requests that have been approved by a reviewer.

  • pr-reviewed-changes-requested These issues relate tp pull requests for which a reviewer has requested changes.

  • pr-unreviewed These issues relate to pull requests that have not been reviewed yet.

  • project-design-book These issues relate to the content of the project design book.

  • project-management We like to model best practice, so The Turing Way itself is managed through these issues. These issues help us to coordinate some logistics.

  • question 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.

  • ready-for-merge These issues can be used after approving a pull request to let the author know that they can merge it.

  • reproducibility-book These issues relate to the content of the reproducibility book.

  • research-related-theory These issues relate to the theoretical side of research best practices.

  • review-request These relate to pull requests for urgent review requests, for example, to approve a report, abstract, and newsletter.

  • software-skills These relate to issues and pull requests that may need some software development, design, or troubleshooting skills.

  • Tools These issues discuss the 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.

  • translation These issues relate to translating the reproducibility book into other languages.

  • Travel These issues are mainly for the attention of core project members to plan travel to face to face meetings

  • typo-fix These issues relate to fixing typos and broken links.

  • work-in-progress These issues are work in progress.

Making a change with a pull request

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 upfront 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

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 main 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.

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. 😉

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. 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. Please note that you need to 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 🎈.

The process of writing chapters

  • Fork the repository from alan-turing-institute/the-turing-way if you have not done so already.
    • On your fork create a branch with the name as the chapter to be written and create a markdown file on it.
  • If you are a contributor to the project repository, you can also create a branch on the main repository with the same name as the chapter to be written without creating a fork (or a local copy).
  • Copy the relevant part of the chapter template 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 practice 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 the 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 from becoming unmanageable.
  • 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 Institute's main branch.
  • DO not delete the branch as the chapter may continue to undergo improvement and development in the future.

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:

    pip install -r book/website/requirements.txt

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

    cd ./book/website
jupyter-book build .

Style Guide

In The Turing Way's Community Handbook, we have developed a style guide for the project.

The Turing Way style guide will provide guidance and supporting resources for ensuring consistency, readability and accessibility for all our users.

You are welcome to contribute to the style guide by opening a new issue.

Representing The Turing Way

We would LOVE people to give talks about the project or represent The Turing Way in other ways! We have created a 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 @aleesteele, @malvikasharan and @KirstieJane so that they can do their best to support you.

We would appreciate if you could share a short abstract and your presentation by adding them to the conferences folder and some info in the conferences README.md.

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 community handbook, you can read how your contributions will be acknowledged and recorded in The Turing Way. The Turing Way follows the all-contributors specifications. The all-contributors bot usage is described here. You can see a list of current contributors 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 on Slack, the Gitter channel or by opening an issue, and The Turing Way team members 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)