Optional Challenge 1: 404'd

[jas58]

In lesson 5: GH Pages the first optional challenge links to thinkful.com for directions on committing to another's page. The link 404'd for me today.
I tried searching for the title on thinkful.com, which sent me to a repo in GitHub which looped me back to the same 404 screen.
I do not know how to suggest a better link; this is an important part of the lesson for me at this stage in my learning.

[ostephens]

I think that GitHub repo contains the full text of the original Thinkful tutorial? Is this the right information: https://github.com/Thinkful/guide-github-pull-request/blob/master/index.md#time-to-submit-your-first-pr

[jas58]

Perhaps? Thank you for parsing that repo. It was a step too far for me, Git-novice. The remainder of this email is my thought process. I did not feel up to digging into someone's 8 year old repo to understand the full structure and dig down to a single module. As I read through it, it(self) also links to the full GitHub guide, ( https://guides.github.com/introduction/flow/index.html), posing another limitation: This link may also be dead as it only opened the introduction to the full manual, which again was too much for a novice to parse. That is, my computer opened the home page, not anything specific to "flow." Is that a useful note for me when thinking about these workshops? That "all coding is just DIY and OJT". That means the Carpentries don't actually fill a void, instead they do offer a paper bridge one can expect to fall through and then sink or swim? Or are some learners attending a workshop specially to learn what they can ask of a research team member, of data services? That may be specific to my experience in the social sciences in DataCarpentry.

…

On Fri, Jul 1, 2022, 3:44 AM Owen Stephens ***@***.***> wrote: I think that GitHub repo contains the full text of the original Thinkful tutorial? Is this the right information: https://github.com/Thinkful/guide-github-pull-request/blob/master/index.md#time-to-submit-your-first-pr — Reply to this email directly, view it on GitHub <#128 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AMT5MXYV6PODKCX6YPF6PN3VR2VYDANCNFSM52J4QSYA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[tobyhodges]

Indeed, the link pointing to an outdated GitHub Guides URL* indicates that the Thinkful repository is no longer a great resource for the lesson to use. I would suggest a fix there, but the repository has been archived and no longer accepts pull requests.

With that in mind, I suggest that the optional exercise needs a larger redesign, or otherwise should be removed. When I have taught Git, GitHub, and contributing to someone else's repository in the past, I have taken the approach of pairing up learners and demonstrating the steps they need to take to contribute to each other's repositories. One option would be to replace this optional exercise with something similar, where the Instructor can pair learners up and give them the steps to follow to open a pull request on their partner's repository**.

One downside to this is that it is only designed to work in a workshop setting and would not be accessible to learners following the lesson alone. However, the nature of the exercise is such that two people are required - the submitter (learner) who opens the pull request and the maintainer who receives and can merge it - and it may not be possible for us to provide a sustainable framework that would allow self-directed learners to practice this workflow. (E.g. given that the Thinkful repository was archived with >300 open pull requests, I suspect maintaining such an example repository can be a heavy burden.)

* @jas58 if you still want to read it, I believe the correct link to the guide on GitHub Flow is https://docs.github.com/en/get-started/quickstart/github-flow#following-github-flow. I can also recommend the Pull Requests episode of the extended version of the Software Carpentry Version Control with Git lesson in The Carpentries Incubator by @sstevens2.
** The Carpentries Curriculum Team is working on some automated approaches to create example repositories for use in teaching, which could prove helpful for an exercise like this, but I do not expect it to be ready for another few months.

[ostephens]

I think the immediate solution would be to either:

1. remove the optional exercise
2. substitute an alternative link - but I don't know the lesson well enough to know what that might be (maybe the one I found, or maybe the one suggested by @tobyhodges)

Both straightforward fixes apart from deciding the best link in (2)

[tobyhodges]

I've been looking around a bit, and so far the best resource I have found for this is the GitHub Guide to Contributing to Projects. It does not include the step to create a branch for the changes that are being made (i.e. it does not follow GitHub Flow), but it does guide the reader through the steps of forking, cloning, adding, committing, pushing, and opening a pull request. In my opinion it is better practice to make changes on a new branch, so perhaps a note could be added to the exercise text to suggest this, if linking out to this guide.

[jas58]

Thank you, Mr Hodges, for the link options. Ms Stevens' tutorial on YouTube has been very clear. Will her version from SWC be integrated with LC? Or would an optional link to that lesson suffice for someone who wanted to dig deeper than LC's workshop?

…

On Tue, Oct 11, 2022, 4:00 AM Toby Hodges ***@***.***> wrote: Indeed, the link pointing to an outdated GitHub Guides URL* indicates that the Thinkful repository is no longer a great resource for the lesson to use. I would suggest a fix there, but the repository has been archived and no longer accepts pull requests. With that in mind, I suggest that the optional exercise needs a larger redesign, or otherwise should be removed. When I have taught Git, GitHub, and contributing to someone else's repository in the past, I have taken the approach of pairing up learners and demonstrating the steps they need to take to contribute to each other's repositories. One option would be to replace this optional exercise with something similar, where the Instructor can pair learners up and give them the steps to follow to open a pull request on their partner's repository**. One downside to this is that it is only designed to work in a workshop setting and would not be accessible to learners following the lesson alone. However, the nature of the exercise is such that two people are required - the submitter (learner) who opens the pull request and the maintainer who receives and can merge it - and it may not be possible for us to provide a sustainable framework that would allow self-directed learners to practice this workflow. (E.g. given that the Thinkful repository was archived with >300 open pull requests, I suspect maintaining such an example repository can be a heavy burden.) * @jas58 <https://github.com/jas58> if you still want to read it, I believe the correct link to the guide on GitHub Flow is https://docs.github.com/en/get-started/quickstart/github-flow#following-github-flow. I can also recommend the Pull Requests episode of the extended version of the Software Carpentry *Version Control with Git* lesson in The Carpentries Incubator <https://carpentries-incubator.github.io/git-novice-branch-pr/10-pull-requests/> by @sstevens2 <https://github.com/sstevens2>. ** The Carpentries Curriculum Team is working on some automated approaches to create example repositories for use in teaching, which could prove helpful for an exercise like this, but I do not expect it to be ready for another few months. — Reply to this email directly, view it on GitHub <#128 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AMT5MXZU245NEW3L7QKF4NTWCUUDJANCNFSM52J4QSYA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[tobyhodges]

@jas58 I'm afraid I do not think either option is feasible:

@sstevens2's lesson is in The Carpentries Incubator i.e. it is maintained by her rather than Software Carpentry (her lesson is using the Software Carpentry styling, which can be misleading), and due to time constraints I do not anticipate any extra content on branches and pull requests being incorporated into the official SWC lesson any time soon.

The LC lesson could link to Sarah's lesson but, as that project is maintained only by one person (albeit one as amazing as @sstevens2!), there is always the risk that that lesson will also become outdated or disappear. This is exactly what has happened with the Thinkful tutorial that was originally linked.

I think the safest option is to link to a guide that is maintained by someone with a strong interest in keeping it up-to-date. My preference is to link to an updated version of GitHub's guide, that includes a step to create a new branch after cloning. I have opened an issue to suggest the change and I hope the maintainers will agree. If and when that guide is improved, I will open a pull request here to update the link in the optional exercise.

[jas58]

Thank you, Mr Hodges, for setting these in motion. Cordially, Jennifer AW Stubbs

…

On Mon, Oct 17, 2022 at 5:29 AM Toby Hodges ***@***.***> wrote: @jas58 <https://github.com/jas58> I'm afraid I do not think either option is feasible: @sstevens2 <https://github.com/sstevens2>'s lesson is in The Carpentries Incubator i.e. it is maintained by her rather than Software Carpentry (her lesson is using the Software Carpentry styling, which can be misleading), and due to time constraints I do not anticipate any extra content on branches and pull requests being incorporated into the official SWC lesson any time soon. The LC lesson could link to Sarah's lesson but, as that project is maintained only by one person (albeit one as amazing as @sstevens2 <https://github.com/sstevens2>!), there is always the risk that that lesson will also become outdated or disappear. This is exactly what has happened with the Thinkful tutorial that was originally linked. I think the safest option is to link to a guide that is maintained by someone with a strong interest in keeping it up-to-date. My preference is to link to an updated version of GitHub's guide <https://docs.github.com/en/get-started/quickstart/contributing-to-projects>, that includes a step to create a new branch after cloning. I have opened an issue to suggest the change <github/docs#21409> and I hope the maintainers will agree. If and when that guide is improved, I will open a pull request here to update the link in the optional exercise. — Reply to this email directly, view it on GitHub <#128 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AMT5MXZQ4OJ6UBAJ5TWGEX3WDUS7DANCNFSM52J4QSYA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[tobyhodges]

My suggested change to GitHub's guide was accepted so I have opened #131 to replace the broken Thinkful link.

[emcaulay]

Thank you all for the research and discussion here. I am sorry I did not participate earlier.

@jas58 , your recognition of this problem is very HELPFUL! Thank you for sticking through the discussion! @ostephens , thank you for your review and @tobyhodges thank you for digging all the way in and solving the problem!