🎉🙌 Welcome to jupyter-a11y-mgmt repository! 🎉🙌
✨ We're excited that you're here and want to contribute. ✨
We want to ensure that every contributor feels welcome, included and supported to participate in the jupyter-a11y-mgmt project. We hope that the information provided in this document will make it as smooth 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 integrated into the projecta. As you start contributing to jupyter-a11y-mgmt, 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:
- Contributing to jupyter-a11y-mgmt
jupyter-a11y-mgmt is a community-led and collaboratively developed project, which is made possible through funding obtained through the CZI EOSS grants. We, therefore, require that all our members and their contributions adhere to our Code of Conduct (CoC).
There are many ways to get in touch with jupyter-a11y-mgmt team!
- GitHub issues and pull requests
- Join a discussion, collaborate one 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.)
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 jupyter-a11y-mgmt 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://youtu.be/dQw4w9WgXcQ)) to another webpage.
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.
We have tried to make the process to log issues as frictionless as possible. We have created a General issue template (preview the template here) that is meant to serve as a single point of entry to report bugs, suggestions or questions to the development team.
We appreciate all contributions to the project.
All project management, conversations and questions related to jupyter-a11y-mgmt project happens here in the jupyter-a11y-mgmt repository.
The following steps are a guide to help you contribute to the project:
1. Comment on an existing issue or open a new issue referencing your addition
This allows other members of the jupyter-a11y-mgmt 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.
2. Fork the jupyter-a11y-mgmt repository
This is now your own unique copy of the jupyter-a11y-mgmt. 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.
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.
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.
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).
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 jupyter-a11y-mgmt 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 jupyter-a11y-mgmt 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.
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 corresponding GitHub Action.
GitHub has a nice introduction to the pull request workflow, but please get in touch if you have any questions.
We welcome and recognise all kinds of contributions, from fixing small errors, to developing documentation, maintaining the project infrastructure, writing content or helping with outreach activities.
We use the all-contributors bot to acknowledge controbutors. 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.
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! 🙈)
You can do this by closing the pull request and delete the branch (all-contributors/add-<username>).
These Contributing Guidelines have been adapted from the Contributing Guidelines of the BIDS Starter Kit! (License: CC-BY)