✨ 🙌 Welcome to the qhub repository! ✨ 🙌
You're probably reading this because you are interested in contributing to qhub. That's great to hear! This document will help you through your journey of open source. Here, you'll get a quick overview of how we organize things and, most importantly, how 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 qhub, 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.
Git is a handy 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 qhub maintainers are here to help you figure out any of the jargon or confusing instructions you encounter!
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.
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 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. While these 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 the open issues. See if the issue has already been reported or if your idea has already been discussed. If so, it's often better to leave a comment on a current issue, rather than opening a new one. Old issues also often include helpful tips and solutions to common problems.
If you are looking for specific help with qhub or its configuration, check our Github discussions.
When opening an issue, use a descriptive title and provide your environment details (i.e. operating system, Python, Kubernetes and Conda version). Our issue templates help you remember the most important details to include.
There are three issues templates to choose from:
- Bug Report: With this template, create an issue report that can help others fix something that's currently broken.
- Documentation: Use this template to provide feedback on our documentation or suggest additions and improvements.
- Feature request: Is there anything that would make the community work better? Have you spotted something missing in qhub? Use this template to share your feature ideas with the qhub team.
A few more tips:
-
Describing your issue: Try to provide as many details as possible. What exactly goes wrong? How is it failing? Is there an error? "XY doesn't work" usually isn't that helpful for tracking down problems. Always remember to include the code you ran and if possible, extract only the relevant parts and don't dump your entire script. This will make it easier for us to reproduce the error. Screenshots are also great ways to demonstrate errors or unexpected behaviours.
-
Sharing long blocks of code or logs: If you need to include extended code, logs or tracebacks, you can wrap them in
<details> and </details>. This collapses the content, so it only becomes visible on click, making it easier to read and follow.
Check our labels page for an overview of the system we use to tag our issues and pull requests.
You don't have to be a Python or Kubernetes pro to contribute, and we're happy to help you get started. If you're new to qhub, an excellent place to start are the issues marked with the type: good first issue label, which we use to tag bugs and feature requests that are easy (i.e. low entry-barrier or little in-depth knowledge needed) and self-contained. If you've decided to take on one of these problems and you're making good progress, don't forget to add a quick comment to the issue to assign this to yourself. You can also use the issue to ask questions or share your work in progress.
Never made an open-source contribution before? Wondering how contributions work in the qhub world? Here's a quick rundown!
- Find an issue that you are interested in addressing or a feature you would like to address.
- Fork the repository associated with the issue to your local GitHub organization.
- Create a new branch for your changes.
- Commit and push your changes, then on your repo page in GitHub find the branch, click Contribute and 'Open Pull Request'.
- Please provide a description of what the changes do so we can understand them.
These steps are fine for minor uncontroversial changes, but before undertaking major work that you would want to see accepted into the main qhub repo, please ensure you first create an open Pull Request on our repo with WIP (work in progress) in the title, explaining what you want to do. That way we can discuss it to be sure it makes sense for qhub. Or simply create an issue and indicate that you would be interested in solving the problem yourself.