Revisions to all GitHub content

Question

Revisions to all GitHub content

Closed this issue a year ago · 14 comments

In our push to get the Intro to GitHub content created, we may have left some inconsistencies or differences in style among the sections. Once all sections are merged in, the final step should be to read through everything in order and see what needs ironing out.

Answer 1 · 2022-02-21T16:21:15.000Z

We've set a meeting for Friday 2/25/2022 at 4:30 EST / 2:30 MST for a small group discussion (with me, @clyne, @jukent and @ktyle) to plan out the necessary revisions.

Answer 2 · 2022-03-02T16:15:45.000Z

I am going to work on the branches/PR overlap today.

Answer 3 · 2022-03-02T19:05:05.000Z

I'm reading through the forking, branching, and PR content more thoroughly to try and synthesize it better, and I think that "GitHub workflows" (currently covered in the PR chapter) should have its own chapter.

Answer 4 · 2022-04-20T15:42:43.000Z

One thing I've noticed is that we don't have a consistent style guide for "Issues, Discussions, and Pull Requests". Sometimes they're capitalized or not, italicized or not, or abbreviated or not. What is the best approach for being consistent across different pages?

Answer 5 · 2022-04-21T16:01:27.000Z

One thing I've noticed is that we don't have a consistent style guide for "Issues, Discussions, and Pull Requests". Sometimes they're capitalized or not, italicized or not, or abbreviated or not. What is the best approach for being consistent across different pages?

I suggest always capitalizing the terms "Issues", "Discussions", and "Pull Requests".

The reasoning is that we are referring to specific features of the GitHub platform, and they are capitalized on GitHub. Without capitalization, it might not be clear whether we're referring to the Discussions feature of GitHub, or the more general notion of a discussion (for example).

My $0.02. I think consistency is useful in pedagogical material.

Answer 6 · 2022-04-28T18:08:08.000Z

I think that #270 took care of the capitalization issue, but I'll keep an eye out for any other inconsistencies.

Answer 7 · 2022-04-28T18:09:03.000Z

As discussed at today's EWG, myself and @r-ford are both going to take another complete read-through of the GitHub material and assess whether any more revisions are needed at this point.

Answer 8 · 2022-04-29T15:43:29.000Z

I went through all of the material, and here are some comments and suggestions; I'll open a PR soon with the simpler edits.

The first 3 sections look good.

Cloning and Forking a Repository:

~~A nitpick, but you don't need to highlight the link if clicking the copy-to-clipboard icon.~~
Trying to clone the forked <user>/github-sandbox.git after ProjectPythia/github-sandbox.git raises an error because they have the same name. We could solve this by having the user delete or rename the first clone or by cloning in another directory.

Configuring your GitHub account:

In the linked GitHub PAT creation page, step 8 says to select which permissions to grant the token. I think we should tell the user which to choose, but I'm not really sure myself.

Basic version control with git:

~~"...rest of the history!" --> "...rest of the history or just hit Q to exit git log!"~~

Git Branches:

~~Remove last sentence of intro paragraph, since we already made a git branch in the previous lesson.~~
~~We should note that here the repo has been cloned using SSH, since using HTTPS asks for a username and password, unlike the screenshot.~~
Where did newbranch come from?
The user can follow along until the "Merging Branches" section, where a hypothetical branchB is introduced. Do we want the user to be able to follow along until the end?

Opening a Pull Request on GitHub:

~~"Open a Pull Request" --> "Open pull request" (this is what the button says in the screenshot)~~
~~Typo: contributoris --> contributors~~
~~To be clear, do we want users to actually open PRs on ProjectPythia/github-sandbox? I did here, but if a lot of people use this tutorial, it could get messy.~~

GitHub Workflows:

~~Similar issue with the 2 cloned repos with the same name~~
It seems to me like the material here has already been explained in previous sections, but maybe the repetition is actually fine.

Contribute to Project Pythia via GitHub:

Maybe we could walk the user through forking and cloning pythia-foundations, but letting them figure it out would probably be a good exercise.

Answer 9 · 2022-05-02T17:20:42.000Z

Thanks. @r-ford Let me know if you want me to tackle any of these points.

To be clear, do we want users to actually open PRs on ProjectPythia/github-sandbox? I did ProjectPythia/github-sandbox#3, but if a lot of people use this tutorial, it could get messy.

Yes I believe that is the plan. Every now and then we can go in and close PRs.

Answer 10 · 2022-05-02T18:51:42.000Z

To be clear, do we want users to actually open PRs on ProjectPythia/github-sandbox? I did ProjectPythia/github-sandbox#3, but if a lot of people use this tutorial, it could get messy.

Yes I believe that is the plan. Every now and then we can go in and close PRs.

We can explore some automation for this. I think it's pretty simple to set up a bot to auto-close PRs that have gone stale after a certain amount of time.

Answer 11 · 2022-05-02T18:59:21.000Z

https://github.com/marketplace/stale

Answer 12 · 2022-05-04T23:58:14.000Z

With #273 merged, I think the content looks good. I don't think the remaining items in my previous comment need to be addressed unless a user brings up a similar issue.

Answer 13 · 2022-05-05T02:04:44.000Z

I promised to do one last read-through, which I have not done. I'll keep this issue open until I follow through...

Answer 14 · 2023-04-24T21:48:45.000Z

I think with Lily's recent read through and edits we can close this.