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

Even more elaborated contributing instructions #16

Merged
merged 1 commit into from
Mar 17, 2021
Merged

Even more elaborated contributing instructions #16

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 55 additions & 9 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,21 @@

## Table of contents

1. [Prerequisites](#prerequisites)
1. [Contributor roles](#contributor-roles)
1. [Environment](#environment)
1. [GitHub intro](#github-intro)
1. [Content review](#content-review)
1. [Issues](#issues)
1. [Pull Requests](#pull-requests)


## Prerequisites

A **general requirement** for all members is to be familiar with GitHub and get familiar with the `Org` text file format (see [Environment](#environment)).

Still, if you are not comfortable with GitHub at all but are able to provide valuable feedback, pls use comments to a Pull Request. See [Content review](#content-review).

## Contributor roles

We see the following roles for contributors to the course:
Expand All @@ -21,34 +29,44 @@ We see the following roles for contributors to the course:
- Orgs
- Others

A **general requirement** for all members it to be familiar with GitHub and get familiar with the `Org` text file format (see [Environment](#environment)).


### Benevolent Dictator

Semyon Sinchenko.
Semyon Sinchenko, @sem.

### Core reviewers

Supposed to be well familiar with quantum information & computation, preferrably with experience in QML as well. Also, eager to provide critical feedback.
Supposed to be well familiar with quantum information & computation, preferably with experience in QML as well. Also, eager to provide critical feedback.

@gamlo, @Aleksandr Berezutskii, @Sergei Shirkin, @annakey. To be extended.

### Reviewers

Those who don't satisfy the requirements for core reviewers, but still want to review the content being generated.

By default that's everyone who is invited to the #org\_qml\_course Slack channel.

### Authors

Content generators, to be agreed with Benevolent Dictator.
Content generators, to be agreed with Benevolent Dictator. See [Issues](https://github.com/SemyonSinchenko/qmlcourse.ai/issues) to pick up one of the open tasks.

@stm (Python), sharthZ23 (Python, NumPy), @alex.ozerin (NumPy, math), @yorko (ML intro), @Pola Ron (quantum enthropy), @gamlo (hardware), @Sergei Shirkin (PennyLane). To be extended.

### Editors

Editors wait for a PR to be approved, and then introduce their changes fixing grammar, language, etc.

@nmarkova, @vitaliylyalin7000

### Orgs

_Not to be confused with the `Org` text file format._

These guys help organizing/promoting the course.

@yorko, @vtrohymenko


### Others

Expand All @@ -65,7 +83,7 @@ This repository contains org-files with lectures. Semyon chose an `org-mode` bec

It is the topic of discussion and the files format may be changed any time if there are enough reasons.

`pandoc` could be used as universal exporter for `org-mode` files.
`pandoc` could be used as a universal exporter for `org-mode` files.

### Export org-file to pdf

Expand All @@ -87,7 +105,7 @@ It is the topic of discussion and the files format may be changed any time if th

### Org-mode syntax

The syntax of `org-mode` is quite similar to another mark-up languages (markdowm, reStructured, etc.) but allows more low-level options for `LaTeX` and `HTML`.
The syntax of `org-mode` is quite similar to other mark-up languages (markdowm, reStructured, etc.) but allows more low-level options for `LaTeX` and `HTML`.

About `org-mode`:

Expand All @@ -105,14 +123,42 @@ If you are not familiar with GitHub, please take [a short course](https://learng

Each lecture/assignment or any other unit of content gets its own branch and a Pull Request (PR) into the `master` branch. For example, see [Pull Request #1](https://github.com/SemyonSinchenko/qmlcourse.ai/pull/1) with lecture #1 material.

Every PR needs to have at least 4 approves and at least 1 of them from a Core Reviewer. If you see a Pull Request and want to review it you can add yourself as reviewer. All reviews should be made via `Review changes` button in GitHub and all comments should be made in `File changed` tab not in the `conversation`. You shouldn't write to the `conversation` commentaries about specific parts of a Pull Request. `Conversation` is only for discussion and comments about the PR in general.
Every PR needs to have at least 4 approvals and at least 1 of them from a Core Reviewer. If you see a Pull Request and want to review it you can add yourself as a reviewer.

The review process depends on whether a reviewer is familiar with GitHub or not.

### Reviewing without commits (no git fluency required)
Go to a Pull Request with lecture content (e.g. [this one](https://github.com/SemyonSinchenko/qmlcourse.ai/pull/3/files) for lecture 2), further visit the `Files Changed` tab and add your reviewer comments to specific lines.

Example:

<img src="https://habrastorage.org/webt/3m/zv/wv/3mzvwvnqmeatuuyvob5qpvfvobk.png" />

All comments should be made in the `File changed` tab not in the `Conversation`. `Conversation` is only used for discussion and comments about the PR in general.

### Reviews as commits (basic git fluency required)

We don't want to mess up the process with too many brnaches. Thus, each lecture gets its own feature branch, the review is done via a PT to `master`, and all modifications are introduced as commits to the same feature branch and thus shows up in the same PR.

The preferred way to commit your changes is to:

- Write a message like "I need 2 hours for a review" in the `Conversation` tab. Thus you mention that you are the person modifyig the content right now
- Introduce your changes, mainly to `org` files
- Commit changes to the same feature branch
- Tell others that you are done with your review

Example:

<img src="https://habrastorage.org/webt/1f/fa/ob/1ffaobyn99cuc58fa19pvse_pvw.png" />




## Issues

- If you want to add something new to the course you should start with creating of issue with label `enchancement` where you need to describe your idea;
- If you want to add something new to the course content you should start with creating of an issue with label `enhancement` where you need to describe your idea;
- If you see an open issue without assignment and with a label `help wanted`, you can write a comment that you can do it and you will be assigned to this issue.

## Pull Requests

- If you was assigned to an Issue, you need to create a new branch. When you finish your work you make a Pull Request where you tag the initial issue.
- If you were assigned to an issue, you need to create a new branch. When you finish your work you make a Pull Request where you tag the initial issue.