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.

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

Contributor Onboarding (First chapter or two) #12

Open
wants to merge 14 commits into
base: master
Choose a base branch
from
3 changes: 3 additions & 0 deletions ci/vale/styles/Vocab/main/accept.txt
Original file line number Diff line number Diff line change
Expand Up @@ -34,3 +34,6 @@ colocated
https
http
[cC]yber
[oO]nboarding
repo
Kanban
5 changes: 5 additions & 0 deletions src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,10 @@

[Notice](./notice.md)

- [Contributor Onboarding](./onboarding/main.md)
- [GitHub Tickets](./onboarding/github.md)
- [Markdown](./onboarding/markdown.md)
- [Git](./onboarding/git.md)
- [Pull Requests](./onboarding/pr.md)
- [Supernode 1](./network/supernode1.md)
- [Managing Secrets](operations/secrets.md)
3 changes: 3 additions & 0 deletions src/onboarding/git.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Git

In progress.
61 changes: 61 additions & 0 deletions src/onboarding/github.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# GitHub Tickets

GitHub is a service that provides code hosting and versioning. We also use it for its collaborative features, such as issue/bug tracking and project boards. This documents explains how to use GitHub to keep track of tasks.

## Repositories

The main repository for the Toronto Community Network can be found on GitHub under [tomeshnet/toronto-community-network](https://github.com/tomeshnet/toronto-community-network).

![homepage](./images/homepage.png)

A repository (or "repo") is a collection of files, issues, and project boards grouped under a name. The name of this one is `toronto-community-network` and that it was created by the [tomeshnet](https://github.com/tomeshnet) organization.

An overview of the files and folders is displayed in the middle of the screen, and below that the README is shown, which is a file that explains what the repository is for. If you click on `README.md` you'll see it has the same contents as the text on the homepage.

## Issues

If you click on `Issues` tab you'll see this:
makew0rld marked this conversation as resolved.
Show resolved Hide resolved

![issues](./images/issues.png)

This tab provides a list of all the issues that have been created for this repository. Issues are similar to the idea of "tickets" or bug reports. It allows us to keep track of tasks or potential plans. All issues have numbers, referenced with a hashtag, such as #32, which can be found [here](https://github.com/tomeshnet/toronto-community-network/issues/32).
makew0rld marked this conversation as resolved.
Show resolved Hide resolved

For any issue, there is an initial comment explaining what the issue is for, and a discussion going on below about the issue, with reactions, editing, links, etc. The initial comment will change and get edited by others over time as new information is known.
makew0rld marked this conversation as resolved.
Show resolved Hide resolved

![issue initial comment](./images/issue_initial.png)

Issues also have assignees, which can be seen in the sidebar. These are the users responsible for completing this task. A user can assign themselves or other people.

Issues can either be open or closed, which denotes their completion. Issues are closed once they're no longer relevant, or when the original task or bug has been fixed.
makew0rld marked this conversation as resolved.
Show resolved Hide resolved

## Labels

Issues can have labels, projects, and milestones, which are shown on the sidebar. If a label is clicked, all the issues with that label can be viewed. For example, here are all the communications issues:

![communications issues](./images/issue_comms_label.png)

Using the sidebar, you can filter by other labels if needed.
makew0rld marked this conversation as resolved.
Show resolved Hide resolved

![filter labels modal](./images/filter_labels.png)


## Projects

[#32](https://github.com/tomeshnet/toronto-community-network/issues/32) is also linked to a project, as can be seen in the sidebar.

![sidebar project](./images/sidebar_project.png)

If you click that text or click the Projects tab at the top, you'll be able to see the project. Repositories can have multiple projects, but in this repository there is just one. Here is what it looks like:
makew0rld marked this conversation as resolved.
Show resolved Hide resolved

![project view](./images/project.png)

A GitHub Project is a type of [Kanban](https://en.wikipedia.org/wiki/Kanban_%28development%29) board for organizing issues.
Each of the cards are issues, which can be in different columns. We use a standard setup with To Do, Doing (aka "In Progress"), and Completed columns.
We also have a Backlog column on the far left for low-priority tasks. Issues can be moved from column to column as needed, to indicate their status. Issues will automatically be moved to Completed when they're closed.
makew0rld marked this conversation as resolved.
Show resolved Hide resolved

Issues in the project can also be filtered by label by clicking on a label, for example all the communications issues in the project can be seen [here](https://github.com/tomeshnet/toronto-community-network/projects/1?card_filter_query=label%3Acommunications).


## Creating your first issue

TODO
Binary file added src/onboarding/images/filter_labels.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/onboarding/images/homepage.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/onboarding/images/issue_comms_label.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/onboarding/images/issue_initial.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/onboarding/images/issues.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/onboarding/images/project.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/onboarding/images/sidebar_project.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions src/onboarding/main.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Contributor Onboarding
3 changes: 3 additions & 0 deletions src/onboarding/markdown.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Markdown

In progress.
3 changes: 3 additions & 0 deletions src/onboarding/pr.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Pull Requests

In progress.