Incorrect link to install instructions on setup page

[agitter]

setup.md contains the line

Please see this section of the workshop template for instructions on installing Git.

which links to https://carpentries.github.io/workshop-template/#git That site does not appear to have any Git installation instructions.

[xdebbie]

Noted the same issue here

[agitter]

@sstevens2 had a suggestion about this and pointed me to the setup instructions at https://github.com/carpentries/workshop-template/blob/gh-pages/_includes/swc/setup.html

[sstevens2]

Thanks for the reminder @agitter! I think we should update the install directions to live in the setup page for this lesson instead of pointing to the workshop template (since it has changed in a way that doesn't (at least that I know of) link to a rendered version of the install directions. I'm happy to put in a PR with a draft of that update if needed.

[munkm]

Hi @sstevens2! It'd be great if you could update the links in the lesson to that for now. I think we're having this issue because the carpentries workshop template changed from a default of swc (which shows the setup instructions for the base swc lesson) to a general carpentries one. I am sure our learners can follow the unrendered directions, so we can use that for now. However, I do think we need a better long term solution, so I've opened an issue in the template repo too (linked above). If you're interested in submitting a PR, that would be awesome and much appreciated!

We also link to the git install instructions in lesson 14, so if you could update that link as well that would be fantastic.

[munkm]

Ok it seems that a PR was just opened (#737) to resolve that.

[munkm]

We should leave this issue open until we have a resolution to carpentries/workshop-template#660

[sstevens2]

@munkm I'm not sure we should leave the un-rendered setup page linked. I find it a bit hard to read and I know how to ignore the html. I think learners would find this really difficult to read and use. I do think it would be good to see how the maintainers decide in carpentries/workshop-template#660 but think it would be good to copy the existing directions over to the lesson as a place holder until then.

[ErinBecker]

@sstevens2 - I'm in favor of your proposal. We have active workshops and need to make sure that learners are able to access installation instructions in real time.

[munkm]

Ok, if one of you has time to merge that content over here I would be happy to review it.

[munkm]

I do think there are other lessons that are affected by the change brought up in that issue, so a solution that fixes all of the broken links would be to have all of the installation directions render in the default template for now.

[xdebbie]

Yea well a link is still better than no link at all and people finding themselves in a dead-end, but I agree the maintainers should publish that HTML page and fix it with the right link! Because it looks like right now it's unpublished? @munkm

[xdebbie]

ps: omg totally unrelated but @munkm we've attended the same univ. haha fighting Illini!

[munkm]

@xdebbie It is unpublished on the workshop template page because the default template changed (thank you for your PR with the link!!). I think the issue right now is that we have two solutions: one proposal is to move the content into the git lesson to be published in the git-novice setup page, and the other proposal is to publish all installation instructions in the default workshop template. A related point is that the git-novice lesson is not the only lesson affected by the template change. Other lessons linked to the template for instructions too.

[sstevens2]

@xdebbie and @munkm me too! I was at UIUC for my undergraduate degree!

ps: omg totally unrelated but @munkm we've attended the same univ. haha fighting Illini!

[munkm]

Hahaha awesome @sstevens2 and @xdebbie!!! I'm glad we're all connecting this way. 💟

[ErinBecker]

I'm strongly in favor of solution #1 "move the content into the git lesson to be published in the git-novice setup page"

Putting all of the install instructions into the workshop website template leads to a lot of user error (referenced back in the original RFC, but happy to dig it back up if desired).

If we agree with the strategy of moving the instructions to the individual repos, I can start working on the other affected lessons.

[ErinBecker]

I definitely also agree with the earlier comment about having the setup instructions spread across multiple pages being difficult for learners. I propose the following:

1. Move the install instructions for each of the affected lessons to the lesson itself (asap).
2. Set up some magic to pull the correct instructions into a single page, based on the variables used in the template (I don't know how to do this, so would be relying on someone else to implement this. @fmichonneau and @maxim-belkin have both proposed similar solutions for this)

[ErinBecker]

Coincidentally, I believe @maxim-belkin is also a UIUC alum! 😁

[munkm]

I am not against moving the setup instructions to each lesson generally. However, I do find it frustrating that a change happened in the workshop template that affected many lessons and we were not notified of it but are now expected to respond asap to fix it. I think it's worth considering temporarily having the directions render in the main template until a decision is made and all of the affected repos have time to move the install directions over and all links are fixed adequately.

[ErinBecker]

Thanks for the feedback @munkm. My understanding was that the changes to the template weren't supposed to impact any SWC or LC lessons. I'll look into this and see what happened. Does anyone know offhand which commit is the troublesome one? (If not, I can do some digging and report back)

[ErinBecker]

Ah - was it this one? make default "cp"

[munkm]

Yep! I think that's it! It's also linked in carpentries/workshop-template#660

[ErinBecker]

Thanks for confirming! I'm jumping on a call right now with @zkamvar to troubleshoot. Please let me know on Slack if you'd like to join and I'll shoot you the Zoom link. But no pressure, between the two of us, we can figure out a way to make this issue less urgent!

[ErinBecker]

We're reverting the default from "cp" back to "swc" for the moment. That should serve as an immediate bandaid. I'm going to be working on a Google Doc to outline a longer term solution and will post a link to that GDoc momentarily.

[ErinBecker]

Here's the GDoc - I'm just getting it started, but please feel free to jump on at any point. I'll be working on this actively over the next couple of hours and then will be discussing with the Curriculum Team (@zkamvar @fmichonneau) on Tuesday.

[agitter]

Now that https://carpentries.github.io/workshop-template/#git is live again, #737 in this lesson can be reverted.

[munkm]

Now that https://carpentries.github.io/workshop-template/#git is live again, #737 in this lesson can be reverted.

Done in #738 @agitter ! Feel free to review.

[fmichonneau]

Please accept my apologies for this carpentries/workshop-template@f8862b8

I didn't expect that the installation instructions for the Git lessons would have relied on the workshop template. My ill-informed motivation was to make the template more "carpentry-neutral" so SWC would not be the "historical default".

[manuGil]

Hello all,
I am noticed the same issue with that is is discussed here. It seems this has been discussed for a long time, and @Madchild95 has good suggestion. I would like do implement the changes, If no one has done it already, but it seems that the reason for not making the changes to the setup page is the dependency on the workshop template. Any progress on solving the issues caused by an update to the workshop template? I am willing to improve the setup page.

[sstevens2]

@fmichonneau @ErinBecker, was there a decision to keep using the workshop website template for these lessons now there is a rendering link (example: https://carpentries.github.io/workshop-template/#git)?

I'd still prefer to see the setup instructors included in the setup pages for lessons directly rather than linked to the lesson template but I recognize that is complicated as they are so useful in the workshop website as well and it isn't good to maintain them separately.

[MCMaurer]

Hi @sstevens2, thanks for bringing this issue back up! I'm a new postdoc working with the Curriculum Development Team. We discussed this at a recent meeting and have team members actively working on it now.

[kekoziar]

@sstevens2, @MCMaurer. Adding my $0.02: I am in the "keep the install instructions in one place so we only need to update that one place" camp. IMO, it's easier on all maintainers (between all of The Carpentries lessons, there are about a half-dozen each different Python and R lessons now, so why would we have dozens of different install instructions?), workshop instructors/admins, and learners. I especially think it's important to have the install instructions in one place for learners as they get ready for their workshop. Not only is everything in one place so learners aren't needlessly clicking through several lessons to get to the outgoing links, but it preserves the order to install/verify bash before attempting to install git or CLI text editors.

[kekoziar]

Closing. Original issue is resolved. Subsequent conversation has moved to appropriate forums per

thanks for bringing this issue back up! I'm a new postdoc working with the Curriculum Development Team. We discussed this at a recent meeting and have team members actively working on it now.