Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[DOC]- Update contribution guidelines #1080

Merged
merged 4 commits into from
Feb 25, 2022
Merged

[DOC]- Update contribution guidelines #1080

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
75f1ef9
:memo: [DOC]- Update contribution guidelines
trallard Feb 18, 2022
7596bc8
:memo: Remove references to master
trallard Feb 18, 2022
37cc19c
Merge branch 'main' into trallard/contributing
trallard Feb 18, 2022
815a127
Merge branch 'main' into trallard/contributing
costrouc Feb 23, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
215 changes: 140 additions & 75 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,108 +1,173 @@
# Contributing to qhub
# Contributing to QHub

:sparkles: :raised_hands: Welcome to the qhub repository! :sparkles: :raised_hands:
:sparkles: :raised_hands: Welcome to the QHub repository! :sparkles: :raised_hands:

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.
Everyone is welcome to contribute, and we value everybody's contribution. Code is not the only way to help the community.
Your choices aren't limited to programming; as you can see below, there are many areas where we need **your** help.
Answering questions, helping others, reaching out and improving the documentation is immensely valuable to the community.

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.
Whichever way you choose to contribute, please be mindful of respecting our code of conduct.

If you have any questions that aren't discussed below, please let us know through one of the many ways to get in touch.
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.

## Table of contents

- [Contributing to qhub](#contributing-to-qhub)
- [Contributing to QHub](#contributing-to-qhub)
- [Table of contents](#table-of-contents)
- [:computer: Contributing through GitHub](#computer-contributing-through-github)
- [:pencil: Writing in Markdown](#pencil-writing-in-markdown)
- [:sparkle: Where to start: issues](#sparkle-where-to-start-issues)
- [🏷 Where to start: issues](#-where-to-start-issues)
- [Submitting issues](#submitting-issues)
- [Issue labels](#issue-labels)
- [:computer: Contributing to the codebase](#computer-contributing-to-the-codebase)
- [Step-by-step guide to your first contribution](#step-by-step-guide-to-your-first-contribution)
- [Development process - short summary](#development-process---short-summary)
- [If you are a first-time contributor](#if-you-are-a-first-time-contributor)
- [Submitting your contribution](#submitting-your-contribution)
- [Review process](#review-process)
- [Document changes](#document-changes)
- [Cross referencing issues](#cross-referencing-issues)

## :computer: Contributing through GitHub
## 🏷 Where to start: issues

[Git][git] is a handy tool for version control.
[GitHub][github] sits on top of Git and supports collaborative and distributed working.
Before you open a new issue, please check the [open issues][QHub-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.

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!
If you are looking for specific help with QHub or its configuration, check our [Github discussions][QHub-qa].

To contribute via GitHub, you'll need to set up a free account and sign in.
Here are some [instructions](https://help.github.com/articles/signing-up-for-a-new-github-account/) to help you get going.
### Submitting issues

## :pencil: Writing in Markdown
When opening an issue, give it a **descriptive title** and provide as much information as possible.
Our [issue templates][QHub-templates] help you remember the most important details to include.

GitHub has a helpful page on [getting started with writing and formatting on GitHub](https://help.github.com/articles/getting-started-with-writing-and-formatting-on-github).
There are three issues templates to choose from:

Most of the writing that you'll do will be in [markdown][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][rick-roll] (`[link](https://youtu.be/dQw4w9WgXcQ)`) to another webpage.
1. **Bug Report**: With this template, create an issue report that can help others fix something currently broken.
2. **Documentation**: Use this template to provide feedback on our documentation or suggest additions and improvements.
3. **Feature request**: Is there anything to make the community work better? Have you spotted something missing in QHub?
Use this template to share your feature ideas with the QHub team.

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](https://help.github.com/en/articles/about-comparing-branches-in-pull-requests) review easier to read! :sparkles:
A few more tips:

## :sparkle: Where to start: issues
- **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.

Before you open a new issue, please check the [open issues][qhub-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.
- **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.

If you are looking for specific help with qhub or its configuration, check our [Github discussions][qhub-qa].
- **Suggesting a new feature:** When suggesting a new feature, please also add details on how this new feature might impact the users' and developers' workflow.

### Submitting issues
### Issue labels

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][qhub-templates] help you remember the most important details to include.
Check our [labels page][QHub-labels] for an overview of the system we use to tag our issues and pull requests.

There are three issues templates to choose from:
## :computer: Contributing to the codebase

1. **Bug Report**: With this template, create an issue report that can help others fix something that's currently broken.
2. **Documentation**: Use this template to provide feedback on our documentation or suggest additions and improvements.
3. **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.
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](https://github.com/Quansight/QHub/labels/type%3A%20good%20first%20issue) label,
which we use to tag bugs and feature requests that require low-effort (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.

A few more tips:
### Development process - short summary

- **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.
Never made an open-source contribution before? Wondering how contributions work in the QHub world? Here's a quick rundown!

- **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.
#### If you are a first-time contributor

### Issue labels
1. Go to the [QHub repository][QHub-repo] and click the `fork` button on the top-right corner to create your own copy of the project.
2. Clone the project to your local computer:

Check our [labels page][qhub-labels] for an overview of the system we use to tag our issues and pull requests.
```bash
git clone https://github.com/your-username/QHub.git
```

## :computer: Contributing to the codebase
3. Change into the directory:

```bash
cd Qhub
```

4. Add the upstream repository:

```bash
git remote add upstream https://github.com/Quansight/QHub.git
```

Now using the command `git remote -v` will show two remote repositories:

- `upstream`: which refers to the `QHub` repository on Github.
- `origin`: which refers to your personal fork

#### Develop your contribution

1. Find an issue you are interested in addressing or a feature you would like to address.
2. Pull the latest changes from upstream

```bash
git checkout main
git pull upstream main
```

3. Create a branch for the feature you want to work on. Since the branch name will appear in the merge message, use a sensible, self-explanatory name:

```bash
git branch feature/<feature name>
git switch feature/<feature name>
# this is an alternative to the git checkout -b feature/<feature name> command
```

4. Commit locally as you progress (`git add` and `git commit`). Use an adequately formatted commit message,
write tests that fail before your change and pass afterwards, run all the tests locally. Be sure to document any changed behaviour in docstrings.

#### Submitting your contribution

1. Push your changes back to your fork on GitHub:

```bash
git push origin feature/<feature name>
```

2. Enter your GitHub username and password (repeat contributors or advanced users can remove this step by connecting to GitHub with SSH).
3. Go to GitHub. The new branch will show a green **Pull Request** button. Make sure the title and message are clear, concise, and self-explanatory.
Then click the button to submit it.

:warning: - If your commit introduces a new feature or changes functionality, please
ensure you first create an open Pull Request on our repo with `WIP` (work in progress) in the title and marked as draft, explaining what you want to do.
That way we can discuss it
to be sure it makes sense for QHub. Or start by creating an issue and indicate that you would be interested in solving the problem yourself.
This is generally not necessary for bug fixes, documentation updates, etc. However, if you do not get any reaction, do feel free to ask for a review.

#### Review process

Reviewers (the other developers and interested community members) will write inline and/or general comments on your Pull Request (PR) to help you improve its implementation, documentation and style.
Every developer working on the project has their code reviewed, and we've come to see it as a friendly conversation from which we all learn and the overall code quality benefits.
Therefore, please don't let the review discourage you from contributing: its only aim is to improve the quality of the project, not to criticize
(we are, after all, very grateful for the time you're donating!).

To update your PR, make your changes on your local repository, commit, run tests, and only if they succeed, push to your fork.
The PR will update automatically as soon as those changes are pushed up (to the same branch as before).
If you have no idea how to fix the test failures, you may push your changes anyway and ask for help in a PR comment.

Various continuous integration (CI) pipelines are triggered after each PR update to build artefacts, run unit tests, and check the coding style of your branch.
The CI tests must pass before your PR can be merged. If CI fails, you can find why by clicking on the "failed" icon (red cross) and inspecting the build and test log.
To avoid overuse and waste of this resource, test your work locally before committing.

Before merging, a PR must be approved by at least one core team member. Approval means the core team member has carefully reviewed the changes, and the PR is ready for merging.

#### Document changes

Beyond changes to a functions docstring and possible description in the general documentation, if your change introduces any user-facing modifications, they may need to be mentioned in the release notes.

#### Cross referencing issues

If the PR relates to any issues, you can add the text `xref gh-xxxx` where `xxxx` is the issue number to GitHub comments. Likewise, if the PR solves an issue, replace the `xref` with `closes`, `fixes` or any other flavours [github accepts](https://help.github.com/en/articles/closing-issues-using-keywords).

In the source code, be sure to preface any issue or PR reference with gh-xxxx.

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](https://github.com/Quansight/qhub/labels/type%3A%20good%20first%20issue) 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.

### Step-by-step guide to your first contribution

Never made an open-source contribution before? Wondering how contributions work in the qhub world? Here's a quick rundown!

1. Find an issue that you are interested in addressing or a feature you would like to address.
2. Fork the repository associated with the issue to your local GitHub organization.
3. Create a new branch for your changes.
4. Commit and push your changes, then on your repo page in GitHub find the branch, click Contribute and 'Open Pull Request'.
5. 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.


[qhub-repo]: https://github.com/Quansight/qhub/
[qhub-issues]: https://github.com/Quansight/qhub/issues
[qhub-labels]: https://github.com/Quansight/qhub/labels
[qhub-templates]: https://github.com/Quansight/qhub/issues/new/choose
[qhub-qa]: https://github.com/Quansight/qhub/discussions/categories/q-a
[issue-template]: https://github.com/Quansight/qhub/blob/master/ISSUE_TEMPLATE.md
[git]: https://git-scm.com
[github]: https://github.com
[github-branches]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository
[github-fork]: https://help.github.com/articles/fork-a-repo
[github-flow]: https://guides.github.com/introduction/flow
[github-mergeconflicts]: https://help.github.com/articles/about-merge-conflicts
[github-pullrequest]: https://help.github.com/articles/creating-a-pull-request
[github-review]: https://help.github.com/articles/about-pull-request-reviews
[github-syncfork]: https://help.github.com/articles/syncing-a-fork
[markdown]: https://daringfireball.net/projects/markdown
[rick-roll]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
[jerry-maguire]: https://media.giphy.com/media/uRb2p09vY8lEs/giphy.gif
[all-contributors]: https://github.com/kentcdodds/all-contributors#emoji-key
<!-- Links -->
[QHub-repo]: https://github.com/Quansight/QHub/
[QHub-issues]: https://github.com/Quansight/QHub/issues
[QHub-labels]: https://github.com/Quansight/QHub/labels
[QHub-templates]: https://github.com/Quansight/QHub/issues/new/choose
[QHub-qa]: https://github.com/Quansight/QHub/discussions/categories/q-a
[issue-template]: https://github.com/Quansight/QHub/blob/main/ISSUE_TEMPLATE.md
26 changes: 26 additions & 0 deletions RELEASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

> Contains description of QHub releases.
---

## To create a new release:

1. Increment the version number in `qhub/VERSION`
Expand All @@ -16,6 +17,8 @@

### Bug fixes

---

## Release 0.3.13 - 10/13/2021

### Breaking changes
Expand All @@ -42,6 +45,8 @@
- Update `remove_existing_renders` to only delete QHub related files/directories ([#800](https://github.com/Quansight/qhub/pull/800))
- Reduce number of AWS subnets down to 4 to increase the number of available nodes by a factor of 4 ([#839](https://github.com/Quansight/qhub/pull/839))

---

## Release 0.3.11 - 05/07/2021

### Breaking changes
Expand All @@ -55,6 +60,8 @@
- removing default values from pydantic schema which caused invalid yaml files to unexpectedly pass validation
- make kubespawner_override.environment overridable (prior changes were overwritten)

---

## Release 0.3.10 - 05/06/2021

### Breaking changes
Expand All @@ -75,6 +82,8 @@

- terraform formatting in cookiecutter for enabling GPUs on GCP

---

## Release 0.3.8 - 05/05/2021

### Breaking changes
Expand All @@ -89,6 +98,8 @@
- dask-gateway exposed by default now properly
- typo in cookiecutter for enabling GPUs on GCP

---

## Release 0.3.7 - 04/30/2021

### Breaking changes
Expand All @@ -101,6 +112,8 @@

- `jhsingle-native-proxy` added to the base jupyterlab image

---

## Release 0.3.6 - 04/29/2021

### Breaking changes
Expand All @@ -122,6 +135,8 @@
- fixed gitlab-ci before_script and after_script
- fixed jovyan -> qhub_user home directory path issue with dashboards

---

## Release 0.3.5 - 04/28/2021

### Breaking changes
Expand All @@ -136,6 +151,8 @@

### Bug fixes

---

## Release 0.3.4 - 04/27/2021

### Breaking changes
Expand All @@ -146,6 +163,8 @@

- remaining issues with ci_cd branch not being fully changed

---

## Release 0.3.3 - 04/27/2021

### Breaking changes
Expand All @@ -162,13 +181,17 @@

### Breaking changes

---

## Release 0.3.2 - 04/20/2021

### Bug fixes

- prevent gitlab-ci from freezing on gitlab deployment
- not all branches were configured via the `branch` option in `ci_cd`

---

## Release 0.3.1 - 04/20/2021

### Feature changes an enhancements
Expand All @@ -182,6 +205,8 @@
### Bug fixes
- typo in `authenticator_class` for custom authentication

---

## Release 0.3.0 - 04/14/2021

### Feature changes and enhancements
Expand Down Expand Up @@ -256,4 +281,5 @@
* Removed the registry for DigitalOcean.

## Thank you for your contributions!

> [Brian Larsen](https://github.com/brl0), [Rajat Goyal](https://github.com/RajatGoyal), [Prasun Anand](https://github.com/prasunanand), and [Rich Signell](https://github.com/rsignell-usgs) and [Josef Kellndorfer](https://github.com/jkellndorfer) for the insightful discussions.