Skip to content

Commit a5c33d6

Browse files
linamntlinamnt
committed
joels comments and pull-request.md
1 parent 08f3386 commit a5c33d6

File tree

2 files changed

+187
-178
lines changed

2 files changed

+187
-178
lines changed

‎CONTRIBUTING.md

Lines changed: 85 additions & 178 deletions
Original file line numberDiff line numberDiff line change
@@ -8,201 +8,107 @@ The following is a set of guidelines for contributing to the UofT Coders communi
88

99
### Table of Contents
1010

11-
1. [What You Should Know](#what-you-should-know)
11+
1. [About UofT Coders](#about-uoft-coders)
1212
- [Code of Conduct](#code-of-conduct)
13-
- [About UofT Coders](#about-uoft-coders)
13+
1414
2. [How You Can Contribute](#how-you-can-contribute)
15-
- [Running a Lesson](#running-a-lesson)
15+
- [Leading a Lesson](#leading-a-lesson)
16+
- [Creating the Content](#creating-the-content)
17+
- [Teaching in Class](#teaching-in-class)
1618
- [Fixing and Updating the Website](#fixing-and-updating-the-website)
1719
- [Other Ways to Get Involved](#other-ways-to-get-involved)
1820

1921
-----
20-
# What You Should Know
21-
22-
### Code of Conduct
22+
# About UofT Coders
2323

24-
We adhere to a [Code of Conduct](https://github.com/UofTCoders/studyGroup/blob/gh-pages/codeOfConduct.md) and by participating, you agree to also uphold this code. Please report any unacceptable behaviour to [email protected]. If you feel that the exec has been violating the Code of Conduct, please email [email protected] to report.
24+
The UofT Coders group was formed to share and learn about coding techniques and
25+
best practices for computing and analysis in research. We hold weekly sessions
26+
in the format of code-alongs, coworking sessions or journal clubs/discussions.
27+
To see our previous and upcoming events, you can visit our [Events repo](https://github.com/UofTCoders/Events/issues).
28+
To learn more about our group, you can read our [constitution](https://github.com/UofTCoders/council/blob/master/Constitution.md).
2529

26-
### About Uoft Coders
30+
## Code of Conduct
2731

28-
The UofT Coders group was formed to share and learn about coding techniques and best practices for computing and analysis in research. We hold weekly sessions in the format of code-alongs, coworking sessions or journal clubs/discussions. To see our previous and upcoming events, you can visit our [Events repo](https://github.com/UofTCoders/Events/issues). To learn more about our group, you can read our [constitution](https://github.com/UofTCoders/council/blob/master/Constitution.md).
32+
We adhere to a [Code of Conduct](https://github.com/UofTCoders/studyGroup/blob/gh-pages/codeOfConduct.md)
33+
and by participating, you agree to also uphold this code. Please report any
34+
unacceptable behaviour to [email protected]. If you feel that the exec has
35+
been violating the Code of Conduct, please email [email protected] to report.
2936

3037
-----
3138
# How You Can Contribute
3239

33-
## Running a Lesson
34-
### Lesson Instructor Checklist
35-
#### Making the Lesson:
40+
## Leading a Lesson
41+
42+
The Mozilla Science Study Group
43+
handbook [**here**](https://mozillascience.github.io/studyGroupHandbook/lessons.html#reuse)
44+
and [**here**](https://mozillascience.github.io/studyGroupHandbook/event-types.html#workalong)
45+
has several very good points about making a lesson. This section summarizes bits
46+
of the handbook, but also adds pieces that are missing from it. Check out the
47+
[lesson bank too](https://github.com/mozillascience/studyGroupLessons/issues).
48+
49+
### Creating the Content
3650

37-
+ **Use Built-in Datasets**: Use built-in sample datasets instead of requiring attendees to download files.
38-
+ **Keep in mind beginners**: make few assumptions about the knowledge of the audience, unless specified that this is an intermediate level lesson, requiring prior knowledge. Keep it simple.
39-
+ **Minimal use of slides**: If your lesson involves coding, keep slides to a minimum if at all, focus on interactive live-coding.
40-
+ **Code Review**: The lesson code is posted to GitHub along with a pull request to [UofTCoders/studyGroup](https://github.com/UofTCoders/studyGroup) repository at least 1 full day prior to the lesson date to allow for review. See [Making a Pull Request](#submitting-a-pull-request)
51+
+ **Use Built-in Datasets**: Use built-in sample datasets instead of requiring
52+
attendees to download files.
53+
+ **Keep in mind beginners**: Make few assumptions about the knowledge of the audience,
54+
unless specified that this is an intermediate level lesson, requiring prior knowledge.
55+
Keep it simple.
56+
+ **Minimal use of slides**: If your lesson involves coding, keep slides to a minimum
57+
if at all, focus on interactive live-coding.
58+
+ **Code Review**: The lesson code is posted to GitHub along with a pull request to
59+
[UofTCoders/studyGroup](https://github.com/UofTCoders/studyGroup) repository at
60+
least 1 full day prior to the lesson date to allow for review.
61+
See [Submitting a Pull Request](https://uoftcoders.github.io/studyGroup/pull-request/)
4162

4263

43-
#### Giving the Lesson
64+
### Teaching in Class
4465

4566
+ **Arrive early**: Come 10 minutes before the lesson starts to set up.
4667
+ **Introduce yourself**: Start by introducing yourself and perhaps why you're teaching this lesson.
4768
+ **Stay on time**: Keep mindful of the time, lessons are 50-60 minutes long.
48-
+ **Start from the very beginning**. Actually show how to open the program or IDE (RStudio/Jupyter Notebook/Shell/etc)
49-
with everyone else (especially for beginner lessons).
69+
+ **Start from the very beginning**: Briefly explain all aspects of the what you are doing when live-coding including:
70+
- show how to open the program or IDE (e.g. RStudio/Jupyter Notebook/Shell or Terminal/etc)
71+
- how to run code (e.g. press `Shift+Enter` in the Jupyter Notebook)
72+
- if this is an intro lesson, explain the concept of an IDE or shell
73+
- importing modules and packages such as `import numpy as np` or `library(dplyr)`
74+
5075
+ **Live-coding**: Use of slides is minimal, majority of lesson involves writing the code WITH the audience during the lesson
5176
+ **Stay on topic**: There is only one hour, if a question arises that is off-topic, you can always suggest discussing afterwards.
52-
-------
53-
## Lesson Tips
54-
The Mozilla Science Study Group
55-
handbook [**here**](https://mozillascience.github.io/studyGroupHandbook/lessons.html#reuse)
56-
and [**here**](https://mozillascience.github.io/studyGroupHandbook/event-types.html#workalong)
57-
has several very good points about making a lesson. This section summarizes bits
58-
of the handbook, but also adds pieces that are missing from it. Check out the
59-
[lesson bank too](https://github.com/mozillascience/studyGroupLessons/issues).
6077

61-
From the handbook:
62-
63-
- **Keep it short and simple**
64-
- **Keep in mind the beginners**
65-
- **Don't use slides and focus on writing the code**
66-
67-
68-
Expanding on this are other things to keep in mind.
69-
70-
**Data**: External data *should not be used* unless it is absolutely necessary.
71-
Instead, rely on built-in or sample datasets provided by the respective
72-
programming language or package.
73-
74-
**Code**: This is the main thing that should be emphasized. How the code is
75-
used, its specific applications, and its meaning should be the entire focus of
76-
the lesson. Here are some tips:
77-
78-
- Keep the code as *simple* as possible while still covering the concept. The
79-
session is, after all, only one hour.
80-
- When making the code, make *no or few assumptions* about the knowledge of the
81-
audience.
82-
- Keep the code *generalizable*. Our members come from diverse fields of
83-
research. What we share is the need to code.
84-
85-
**Come 10 min** early, to make sure everything is set up.
86-
87-
Before you begin:
88-
89-
- Introduce yourself and ask that everyone else state their name and maybe their
90-
program
91-
92-
A few more tips:
93-
94-
- Start from the *(nearly) very beginning*. Open the program or IDE (RStudio/Jupyter/etc)
95-
with everyone else and show how to do it (for beginner lessons).
96-
- Make *no/few assumptions* about what the audience knows. Let them know what keys
97-
you are using to run a particular piece of code (Ctrl-Enter for
98-
Jupyter/RStudio/etc) (for beginner lessons).
99-
- Write the code *with the audience*. Start from an empty file and write the
100-
code you planned. This forces you to slow down and allows the audience to follow
101-
along much better. If need be, print off the code you wanted to go through to
102-
have the paper beside you.
103-
- Stay *on-topic*. There is only one hour. If an question arises that is
104-
off-topic, say simply that you can talk about that later.
105-
106-
107-
108-
## Submitting a Pull Request
109-
Lessons should be submitted as a Pull Request (PR) at least *one full day* before the
110-
session. Submitting the lessons as a Pull Request is also a great way to find
111-
out whether your lesson matches what is advertised in the Events repo. New lessons
112-
should be created from a copy of the `lessons/template/lesson.md` file. Follow the
113-
details and requests in the template lesson file and write up your lesson!
114-
115-
Follow the instructions below for submitting a PR:
116-
117-
**Brief step-by-step**:
118-
119-
1. Fork the `studyGroup` repo
120-
2. (Optional) `git clone` your forked version onto your computer
121-
3. Use the lesson template and make your lesson
122-
4. Follow the file/folder naming rules (see below)
123-
5. `git add` and `git commit` that lesson
124-
6. `git push` your lesson to your forked `studyGroup` repo
125-
7. Submit a PR using Github's Pull Request button on your forked version
126-
127-
**Detailed step-by-step**:
128-
129-
1. Fork the `studyGroup` into your GitHub account. See
130-
[this GitHub help for info on forking](https://help.github.com/articles/fork-a-repo/).
131-
2. After it is forked, `git clone` from your terminal or Git Bash of your new
132-
forked version of `studyGroup` onto your computer *from your account*. If you
133-
want it on your Desktop do:
134-
```
135-
cd Desktop
136-
git clone https://github.com/YOUR-USERNAME/studyGroup.git
137-
```
138-
139-
...replacing YOUR-USERNAME with your own user name on GitHub (eg: mine would
140-
look like `git clone https://github.com/lwjohnst86/studyGroup.git`).
141-
3. Type `ls` to confirm that the `studyGroup` folder was created. Then
142-
`cd studyGroup` and `git status` or `git log` to confirm that you are now in the
143-
new repo.
144-
4. Add the original Study Group repo using this command:
145-
```
146-
git remote add upstream https://github.com/UofTCoders/studyGroup.git
147-
git fetch upstream
148-
```
149-
150-
5. Create a new folder in the `lessons` folder of `studyGroup` on your computer,
151-
naming it appropriately (without spaces) to the lesson you are planning on
152-
teaching. Files and folders should be named as such:
153-
- Create the lesson template under whichever programming language you are
154-
teaching (e.g. under `lesson/r` or `lesson/python`.). Use the `misc/` folder
155-
if you aren't sure.
156-
- Name the new lesson folder, all small caps, so that it simply explains
157-
what the topic is (e.g. `python/intro/`, `r/loops/`).
158-
- If you need more than one word, keep all small caps and use a dash (`-`)
159-
for a space (e.g. `misc/bash-intro/`, `misc/jekyll-ghpages/`).
160-
6. Copy the `lessons/template/lesson.md` into the new folder and write up your
161-
lesson in there, filling out requested information. This is a
162-
[Markdown](https://help.github.com/articles/markdown-basics/) file (`.md`).
163-
The reason it should be Markdown or plain text is because GitHub
164-
renders the Markdown file into HTML so it's nicer to read on the site and for
165-
others.
166-
167-
7. Save the new file in the git history:
168-
```
169-
git add ./lessons/yourlesson/lesson.md
170-
git commit -m "Added file on lesson"
171-
```
172-
173-
8. Push up to your GitHub repo:
174-
```
175-
git push origin gh-pages
176-
```
177-
9. Submit a Pull Request *from* your GitHub account *into* the UofTCoders.
178-
Make sure the **base fork** is set to `UofTCoders/studyGroup` (and not `mozillascience/studyGroup`).
179-
Check [the GitHub help on Pull Requests](https://help.github.com/articles/using-pull-requests/).
180-
181-
**Note**: For those wanting to contribute regularly or who edit their
182-
repositories often, it's best to create a new branch for each PR you make. For
183-
example, if you want to clean up some bits of the repo, you can follow a
184-
workflow such as this:
185-
186-
```
187-
## Good to name the branch to reflect what you are doing.
188-
git checkout -b cleaningUp
189-
## Make edits/changes/cleaning up
190-
git add files-changed
191-
git commit
192-
git push origin cleaningUp
193-
```
194-
195-
You can now make a pull request **of the `cleaningUp` branch**. Once the pull
196-
request has been completed, you can delete the now old branch via:
197-
198-
```
199-
git checkout gh-pages ## Move back to main branch
200-
git branch --delete cleaningUp
201-
## If you want to delete the remote branch too do:
202-
git push origin --delete cleaningUp
203-
## Update your main branch from the new upstream branch
204-
git pull upstream gh-pages
205-
```
78+
-----
79+
80+
## Fixing and updating the website
81+
82+
There are two ways of fixing or adding to the website, either by:
83+
84+
- Creating an [Issue](https://github.com/UofTCoders/studyGroup/issues/new)
85+
describing the problem or enhancement. This is technically not doing anything
86+
yourself, just recommending something to be done.
87+
- Submitting a Pull Request from a clone of this repo. This way takes a bit more work and requires knowledge of Git and likely HTML. But we
88+
would appreciate any help! No harm in giving it a try! That's a beauty of using Git, it's hard to mess up and break something.
89+
90+
If you want to view the website before submitting a Pull Request to make sure
91+
your changes are as you expect, you'll need to:
92+
93+
- Install Jekyll by following these [instructions](https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/).
94+
- To build the site locally, run `jekyll serve`.
95+
- The built site can also be viewed at your forked version
96+
(`https:://yourusername.github.io/studyGroup`).
97+
98+
----
99+
100+
## Other Ways to Get Involved
101+
102+
### Helping Out at Our Events
103+
104+
We hold various sessions that incorporate code-alongs, and having the help of more advanced users to help out the beginners is very much appreciated.
105+
- If you see a session topic that is more beginner than your current level, we highly encourage you to attend anyway and help answer questions or provide more one-on-one support during lessons.
106+
- You can also lend a hand at our co-working sessions to people who have come to work on their own projects.
107+
- We do a call for helpers for all our Software Carpentry workshops, and we definitely wouldn't be able to run these without the help of volunteers like you!
108+
109+
### Taking On A Leadership Role
110+
111+
The planning and organization of our the group and our various events are done by our executive council. We hold elections every April to elect the executive council members, however, we are always open to suggestions on new roles and positions for interested members of the UofT Coders community who wish to take on more a leadership role. To read more about these positions, please see our [Council Roles](https://github.com/UofTCoders/council/blob/master/Council_Roles.md) document.
206112

207113
-----
208114

@@ -213,7 +119,7 @@ There are two ways of fixing or adding to the website, either by:
213119
- Creating an [Issue](https://github.com/UofTCoders/studyGroup/issues/new)
214120
describing the problem or enhancement. This is technically not doing anything
215121
yourself, just recommending something to be done.
216-
- Submitting a Pull Request from a clone of this repo. This way takes a bit more
122+
- [Submitting a Pull Request](https://uoftcoders.github.io/studyGroup/pull-request/) from a clone of this repo. This way takes a bit more
217123
work and requires knowledge of Git and likely HTML. But we would appreciate any
218124
help! No harm in giving it a try! That's a beauty of using Git, it's hard to
219125
mess up and break something.
@@ -222,7 +128,7 @@ If you want to view the website before submitting a Pull Request to make sure
222128
your changes are as you expect, you'll need to:
223129

224130
- Install Jekyll by following these [instructions](https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/).
225-
- To build the site locally, run `jekyll serve`.
131+
- To build the site locally, run `jekyll serve`.
226132
- The built site can also be viewed at your forked version
227133
(`https:://yourusername.github.io/studyGroup`).
228134

@@ -232,11 +138,12 @@ your changes are as you expect, you'll need to:
232138

233139
### Helping Out at Our Events
234140

235-
We hold various sessions that incorporate code-alongs, and having the help of more advanced users to help out the beginners is very much appreciated.
236-
- If you see a session topic that is more beginner than your current level, we highly encourage you to attend anyway and help answer questions or provide more one-on-one support during lessons.
237-
- You can also lend a hand at our co-working sessions to people who have come to work on their own projects.
141+
We hold various sessions that incorporate code-alongs, and having more advanced users to assist beginners during the lesson is very helpful.
142+
143+
- If you see a session topic that is more beginner than your current level, we highly encourage you to attend anyway and help answer questions or provide more one-on-one support during lessons.
144+
- You can also lend a hand at our co-working sessions to people who have come to work on their own projects.
238145
- We do a call for helpers for all our Software Carpentry workshops, and we definitely wouldn't be able to run these without the help of volunteers like you!
239146

240147
### Taking On A Leadership Role
241148

242-
The planning and organization of our the group and our various events are done by our executive council. We hold elections every April to elect the executive council members, however, we are always open to suggestions on new roles and positions for interested members of the UofT Coders community who wish to take on more a leadership role. To read more about these positions, please see our [Council Roles](https://github.com/UofTCoders/council/blob/master/Council_Roles.md) document.
149+
The planning and organization of our the group and our various events are done by our executive council. We hold elections every April to elect the executive council members, however, we are always open to suggestions on new roles and positions for interested members of the UofT Coders community who wish to take on more a leadership role. To read more about these positions, please see our [Council Roles](https://github.com/UofTCoders/council/blob/master/Council_Roles.md) document.

0 commit comments

Comments
 (0)