[Feb 4 merge] Review GitHub lessons 0-3 #105
Conversation
lwasser
changed the title
github-git/1-get-to-know-repo.md
Outdated
| ### Answer these questions | ||
|
|
||
| * Does the repository accept contributions? If so, what types of contributions are accepted? | ||
| * Does the repository use specific code or text formatting standards or liters? |
There was a problem hiding this comment.
I think there is a typo: "liters" --> "linters"
github-git/2-identify-issue.md
Outdated
| * [Make your changes on a new branch in your fork.](4-edit-commit-files) | ||
| * [Submit a pull request](5-pull-request) with your updates. | ||
|
|
||
| A gentle nudge is ok if maintainers don't respond after a few weeks. That might look something like this: |
There was a problem hiding this comment.
This seems to repeat the content in lines 79–81.
|
@all-contributors please add @jsdodge for review |
|
I've put up a pull request to add @jsdodge! 🎉 |
github-git/3-fork-repo.md
Outdated
|
|
||
| Fork the [pyOpenSci example repo](https://github.com/pyOpenSci/pyos-demo-package-contribute). Remember that a fork is a copy of a repository that is owned by someone else or an organization that lives in your GitHub account. | ||
|
|
||
| **2. Open the file that you proposed changes to in the issue you selected in the [how to identify an issue lesson](2-identify-issue).** |
There was a problem hiding this comment.
This point seems out of context of the rest of the page, and more like the starting point of edit-commit-files.
There was a problem hiding this comment.
oooh good catch that is a copy/paste error. i've reorganized these a few times already.
github-git/3-fork-repo.md
Outdated
| --- | ||
|
|
||
| (fork-repository)= | ||
| # How to Fork a GitHub Repository |
There was a problem hiding this comment.
This is a different workflow, and so might not be easy to teach along side the lesson you have now, but if all edits happen in the browser, navigating to the file to be edited first and clicking the edit pen button will take the user to an alternative Fork this repository page (only if you haven't yet forked).
There was a problem hiding this comment.
OH gosh - so true. I discovered this when creating the screen captures!
What is so hard is that there are actually multiple potential paths here! I thought about an overview page (i have a draft online here that also shows them the various paths in case they happen to do what you just mentioned!
But we stick with "first principles," so to speak, in this lesson, which would be the traditional issue, fork, work, commit, pr route.
I want to show them one way clearly. But then maybe have a resource page that shows alternative paths?
what do you think about that?
There was a problem hiding this comment.
Probably best to stick to one workflow. And what you have is the more general, probably seen as more "proper" as it is how you would make a fix locally.
Best to keep it simple. I'll just note that every PyOS sprint I have gone to, I've encouraged attendees to go straight for the edit button.
There was a problem hiding this comment.
Yup. ok cool. yes i think we can in the future show them those workflows as well (i've done that too in sprints).
i've started this page below:
https://www.pyopensci.org/lessons/github-git/ways-to-contribute.html
to capture the various ways you can create a pr! That way we have that documented for sprints too (we can work on it together via a future review as well). i plan to open more pr's here with a fresh version of each lesson so we can review it as if it's new after i get this grant deliverable in today (its done!).
Also, for me, https://www.pyopensci.org/lessons/github-git/0-first-contribution.html is returning 404 |
github-git/0-first-contribution.md
Outdated
|
|
||
| Contributing to open source in a public space like GitHub can feel intimidating. You may not know the project maintainers, feel unsure about your GitHub skills, or wonder where to begin. | ||
|
|
||
| This lesson series will teach you how to collaborate on code and documentation using GitHub. It will help you confidently contribute to a GitHub repository and build skills to collaborate with colleagues (some of whom you may not have met in real life!). |
There was a problem hiding this comment.
what's the context for these lessons? do the students already know rough contours of what open source is, why one might want to contribute to something, etc.?
There was a problem hiding this comment.
I suspect we need a context page. I"m going to update this page (i just merged Jeremiahs inline stuff). I reorganized this (but I want your feedback) to be a set of activities with links to the background for each. i'm not sure if this is the best way or not.
but this is what i imagine
we have sprints regularly and people come that are new to contributing. I can send them to this page and it walks them through all of the steps with background information on each following page on how to implement each. I've never designed a lesson like this before, so I'm not sure how it will land. So i think we might want to add a context page first about contributing and github (potentially?) That context might be something like this page with more focus on open source.
these pages are online because i have a grant deadline but i still want to do reviews like we always do ❤️
github-git/1-get-to-know-repo.md
Outdated
| --- | ||
|
|
||
| (get-to-know-repo)= | ||
| # Get to Know a (new to you) GitHub Repository |
There was a problem hiding this comment.
in my experience, one of the most intimidating things from ppl i have helped mentor who are venturing out and doing their first contribs is fear of reprisal/actually getting yelled at/PRs getting closed without discussion/etc. I think somewhere in this lesson it's worth spending time introducing the idea that each project has its own culture, history, and norms, and that navigating those norms is as important as knowing the technical side of how to make a contrib. I think this is already present in the lesson in different places, but I think here at the intro to this section would be good place for that framing to be made explicit.
Part of that that I think we in particular can do well where other tutorials like this fail is in being reassuring - open source can be wonderful, but you will also inevitably accidentally wander into a pit of assholes, and you should know that as long as you are doing your best to understand the norms and be respectful that you aren't doing anything wrong. This is to put in perspective why there is so much ritual around making a contrib - e.g. high volume projects they are dealing with a huge amount of work all the time, so they have to make rules and processes to make that manageable. I think without that context it might be a little unclear why you have to go through all this rigamarole when the "open PR" button is right there and i can click it at any time
There was a problem hiding this comment.
awwww such a good point Jonny!!
In some of the other lessons i started adding little social cue tips but they are all a bit too maintainer focused (avoid getting yelled at) and could be more supportive.
My one question is - should the overview / culture stuff be in its own intro or here ? it could fit here well too especially when talking about code of conduct, etc.
There was a problem hiding this comment.
I did some redesigning here, sprinkling social cues throughout. But I welcome other places for more encouraging language. I don't think i've hit this comment well yet. But it's the most important one. I think the context you mention is really important.
When i've worked with people it's always pyOpenSci that they are contributing too. they are always afraid of breaking something.
your point is what I've personally experienced, especially early on - the fear of doing things wrong and potential repercussions. how do we gently nudge and support here?!
github-git/0-first-contribution.md
Outdated
| The steps for making your first contribution to an open source repo. In this lesson, you will do all of your work on GitHub.com, meaning you don't need to clone or make a copy of your repository locally. This is a great way to get started with contributing. It minimizes the command line skills that you will need to use git. | ||
| ::: | ||
|
|
||
| ## Documentation counts! |
There was a problem hiding this comment.
This comes a little bit out of nowhere, we are still in overview mode and we're already talking about what kind of PRs we can make. Seems like this would fit better in "identify issue"
There was a problem hiding this comment.
It does! I'm going to address these comments now and then update this doc, as I did rework this section a bit. But now i see Jeremiah's comment below about small pr's not being welcome in some projects! i just didn't know that was a thing.
github-git/2-identify-issue.md
Outdated
|
|
||
| In this lesson you will create or comment on an issue that you'd like to fix in GitHub repository that you don't own. | ||
|
|
||
| :::{admonition} Activity: Create (or find) an issue for a bug that you'd like to fix |
There was a problem hiding this comment.
Along the same lines as @jsdodge 's comment on this line, this comes a little bit out of order for me. So in the flow of the lesson we have just finished getting to know the repository. Presumably in reality we are starting from the place of already using the package and noticing something wrong as step -1, and while I understand the idea behind the dummy repository, it seems odd to start this section with "go look for a bug." maybe this should come at the end of this document?
github-git/2-identify-issue.md
Outdated
| Once you have submitted an issue and someone has responded positively, you can begin working on the changes in your fork. [You will learn how to fork a repo, next.](fork-repo) | ||
| ::: | ||
|
|
||
| As you scan the issues, look for beginner-friendly labels. Beginner-friendly labels are a clear message that the project welcomes new contributors. Many projects label issues as **good first issue** or **beginner-friendly** to highlight approachable tasks that are approachable for new contributors. |
There was a problem hiding this comment.
maybe something along the lines of "picking up existing issues, even though they might not be related to the current problem you are experiencing, are a good way of getting to know and building rapport with the developers. remember you're trying to propose changes to something potentially very dear to them! a small bugfix for a known issue to signalt hat you can come in peace can go a long way"
github-git/2-identify-issue.md
Outdated
| 1. Click on the new issues button. If there is a template that you can select for the issue, use one. | ||
|
|
||
| 1. Write a **clear title** summarizing what you’d like to fix. Some repositories use templates—fill them out if available. | ||
| 1. Be **specific about what you'd like to fix**: |
There was a problem hiding this comment.
- "an issue should ideally be about a single thing" (even though what a "single thing" is is an ill-defined problem)
github-git/3-fork-repo.md
Outdated
| `https://github.com/pyopensci/repo-name` | ||
|
|
||
| (fork-repo)= | ||
| ## What is forking a GitHub repository? |
There was a problem hiding this comment.
similar comment re: structure as in section 2 of the lesson - two big ideas in this section: "what is a fork" and "how to make a fork"
currently
## How to fork a GitHub repository
## Who owns a GitHub repository?
## What is forking a GitHub repository?
## A few tips about forking a repo
could be
## What is a fork?
### ... info about what forks are
## How to fork a GitHub repository
### ... info on how to make a fork
There was a problem hiding this comment.
i will reorg some tomorrow. One thing I was considering here was put the action items at the top, considering people have limited attention spans these days. And then explanation below.
I can't decide. We are living in a world of video shorts and such so i wondered what would happen if the "how to" was at the top and the "understand what you just did" came later. As an educator, it's not my preference, but do people online have the attention span to read it all, or do they want to skim and go back to learn?
thoughts?
github-git/3-fork-repo.md
Outdated
|
|
||
| It also means you can update your fork anytime, as the parent repository is updated to ensure it stays in sync. | ||
|
|
||
| 2. If you have already forked the repository but some time has passed. You should consider updating or syncing your fork. GitHub has a sync button that you can use to do this (`pyopensci/repo-name`). This will ensure that all of the files in your repository are current. |
There was a problem hiding this comment.
re: this, i think it would be worth having a "forks v. branches" subsection in "what is a fork?" section - along the lines of "a fork is an independent copy of a repository, you have a double of all the branches (or maybe just main depending on options), in your fork, so if they do work upstream, your version of main will get out of date." which would give this a place to live, as well as allow us to discuss stuff like why you should work on branches even in your fork so you can sync main when needed and leave links for further reading on rebasing/merging to keep a fork up to date.
There was a problem hiding this comment.
Yes definitely a good call. I started a graphic that captures this but will add a bit more text either today or next week. We can leave this open for longer if needed to really get the lessons right now that the grant deliverable is in.
the last deliverable is community review 🚀 and it makes everything better.
|
frick i thought i was gonna make just one or two comments but then i got to reading and made a billion. sorry for not collecting in a review and also looking very good and this is yet another lesson that i badly need a good version of all the time! thank you for writing this! |
github-git/0-first-contribution.md
Outdated
|
|
||
| Further, if you go to contribute and find that the contributing guidelines lack detail, that could also be a useful place for you to start. | ||
|
|
||
| :::{admonition} A real-life first contribution to PyPI |
There was a problem hiding this comment.
I'd rather have some stories that others could share than just mine :) ideas welcome
github-git/0-first-contribution.md
Outdated
| "og:image:alt": An image that shows the steps for contributing to open source on GitHub. | ||
| --- | ||
|
|
||
| # Mastering GitHub Collaboration Skills |
There was a problem hiding this comment.
@sneakers-the-rat, have a look at this version and see what you think. it's a different approach - but it gives the learner the steps first and then it sends them to pages with more info. (if they need it). i just don't know how this will land with people.
github-git/0-first-contribution.md
Outdated
|
|
||
| ******** | ||
|
|
||
| ## Many people's first contributions are to documentation |
There was a problem hiding this comment.
from @sneakers-the-rat try to incorporate the learner's perspective here
- Sometimes, a learner will notice documentation bugs that a maintainer misses.
github-git/0-first-contribution.md
Outdated
|
|
||
| ## Many people's first contributions are to documentation | ||
|
|
||
| In this lesson, you make your first open source contribution by updating documentation (including docstrings) rather than code. Many people start with small fixes like typos, which are simpler to contribute as you don't always need a development environment but are still valuable. Developers often focus on code, leaving less time for writing and editing documentation. So your small contributions can have a large impact. |
There was a problem hiding this comment.
from @ucodery - some projects do NOT welcome small pr's. i need to know more about that to write about it! i had no idea that was a thing and I've never encountered it. Jeremiah, any feedback is welcome!!
|
Hi, y'all 👋🏻 I'm working in two places - locally to meet my Feb 1 grant deadline and here where I want all the input. We can always leave this open for a bit longer to really nail things down before merging. I have some graphics, too, that I'll try to share here and, if not here, in the next pr. Thank you as always for being so collaborative in developing these lessons. your feedback and effort in making lessons better is one of my parts of lesson development here at pyOpenSci ✨ |
|
Ok y'all rock I've incorporated I think all of the comments and updated the lessons. In the preview you can see the graphics and such, too. Please ignore the later lessons; we will do a separate review for that. The plan now is:
|
|
Graphics fork repo
|
|
contributing path
|
Sorry - https://www.pyopensci.org/lessons/github-git/your-first-contribution.html I renamed the files removing the numbers from them. |
Don't worry about this @sneakers-the-rat for me, my github notifications are carefully curated so i saw all of the comments at once - no big deal at all. I'm so used to pr's with hundreds of comments it's not an issue for me when people forget to hit the review button anymore. :) thank YOU (as always!!) for all of the great feedback. lessons are already monumentally better. |
|
ok everyone. I'm going to merge this as planned today. I will be opening up additional lessons for review later this week. we can do a rereview if need be of lessons in the future as well. |
lwasser
force-pushed
the
review-0-3
branch
3 times, most recently
from
c8e7ff3 to
799b13a
Compare
Delete github-git/1-get-to-know-repo.md Delete github-git/2-identify-issue.md Delete github-git/3-fork-repo.md hack: way to allow review of lessons Updates from review
Update github-git/1-get-to-know-repo.md Apply suggestions from code review Co-authored-by: Jeremiah Paige <[email protected]>
Update github-git/0-first-contribution.md Fix: edits from review
add: new content to edit file lesson docs: update README.md [skip ci] docs: update .all-contributorsrc [skip ci] add: edit lesson fix: pr page plus screencasts fix: rename and reorg add: metadata to core pages rewrite: social cues added throughout fix: metadata fix: add social elements fix: cleanup and add social context fix: edits from group review fix: new landing page - intro Fix: final edits to lessons fix: links add: new content to edit file lesson docs: update README.md [skip ci] docs: update .all-contributorsrc [skip ci] add: edit lesson fix: pr page plus screencasts fix: rename and reorg add: metadata to core pages rewrite: social cues added throughout fix: metadata fix: add social elements fix: cleanup and add social context fix: edits from group review fix: new landing page - intro Fix: final edits to lessons fix: links
|
merging this now!! lessons will be live in about 10 minutes 🚀 |
These lessons are already online to meet a deadline. However, I wanted to make sure we could have a normal review process on them!
Therefore, this is a hacked branch that allowed me to create a pr with the 4 files in the lessons that can be reviewed as "new" files.
If you want to see the lessons rendered, you can either check Ci OR you can have a look here for context. these lessons do have some images and we can always add more.
I'm looking for feedback on how the lessons read, The goal is to use them in our sprints and to make it easier for people to make first contributions to open source (which we normally have happen in our sprint events!).