100 change to ssh

[emcaulay]

Resolves #100.

This is a major revision.

In order to address the change in authentication required by GitHub and to implement The Carpentries selected approach (SSH), I needed to move some of the Git configuration into Episodes 2 and 3 of the Lesson. There are revisions to the

• prerequisites for the lesson
• the setup for the lesson
• Episode 2
• Episode 3

I appreciate all reviewers for their time in reviewing this work and welcome suggestions and corrections.

[doingarchives]

Would it be possible to use a consistent and sequential naming / numbering scheme for infographics? This would facilitate future maintenance tasks. Open to many approaches on the name - 'image001lcgit'?

See ISO 5127:2017(en)

3.2.1.04
image
retinal pattern formed by light reflected or transmitted by external stimuli, whose impression is completed by the physiological mechanisms and mental processes that affect visual perception (3.1.1.33)

Note 1 to entry: In graphic technology, the term is commonly used to identify any picture, drawing, illustration, graphic, text or other reproduction, visible to the human eye, that portrays the original in the proper form, colour and perspective.
[SOURCE: ISO 12637-1:2006, definition 31]

Note 2 to entry: “Image” generally refers to any kind of viewing perception, not only to that of pure pictorial content. In this general capacity, “image” also includes e.g. pure text (3.2.1.05) which itself consists solely of graphic/writing (3.1.11.01)characters (3.1.4.02). Thus, in certain data processing (3.1.12.01) operations, processing and display (3.1.11.14) of pure text nevertheless takes place as “image processing” (e.g. in an “image catalogue”).

Note 3 to entry: The ‘external stimuli’ can, when applying certain technical operations like photographing (3.3.5.15), be fixed onto a data medium (3.1.1.39) and thus a document (3.1.1.38) be created from the image.

Note 4 to entry: See also “picture” (3.4.7.51) and ISO 21127:2014, classes “E 36” and“E 38”.

[doingarchives]

Not thrilled by reference within a course to material covered in another course. In my view, there are learners in the audience that take specific courses (not sure what percentage - that would be useful data). For these learners, elliptical references can multiply their sense of frustration - something the text here is already anticipating. Also I find this passage to make assumptions about the learning process that are unfortunate (negative outcomes as normal). Again I'm open to assisting on this or socialising the conversation - the reference would work better if the instruction were internalized.

[doingarchives]

Kindly see prior comment.

[doingarchives]

Not fond of unnecessary capitalisation - is 'Git' a trademarked term? I've also considered the 'Dracula' example a bit tone deaf and socially fraught. ISO / IT terms that are neutral would be better 'Your Name' / 'yourname@address.org'

[doingarchives]

Suggest
with git is the language. Although some of the language used is ...

[doingarchives]

See prior comments ...

[doingarchives]

The text editor selection and specification has always been problematic in this lesson. There has to be an open source option available - I used BBEdit (not free) - a better way would be to discuss the topics and commands as if any text editor would work. Again we don't have useful data on instructor practices, I'm guessing there is a high degree of variation among instructors - they use what is on their machines used for the class.

[doingarchives]

Savvy librarian (like Dracula) is socially awkward and value laden. General comments on the use of capitalization discussed elsewhere. Understand the SSH discussion is the main point here. Acronym should be translated in plain English before the letters SSH. The crypto details should be left for another course / topic ... it appears to be answering a need that is not real (lines 102-106). Drop 'Because generally speaking .... (line 115); also Your output is going (131) - this information is not really adding anything instructional (it is observational and individual experiences will vary confusingly). (line 163) This 'make a note of it' is contrary to many best practices - we were specific about text editors, why not secure password solutions - just avoid this if possible.

[doingarchives]

Choice of a license should reflect the 'open' nature of Library Carpentries - something to the effect of unless there is a legal or economic requirement ... open Creative Commons licenses are always the better choice.

[doingarchives]

See earlier comment about consistent and sequential text and image assets.

[doingarchives]

See earlier comment about consistent / sequential naming of assets.

[doingarchives]

Consider this text (from Apple) - something like this would work well for LC audiences

"If you’re new to using the command line and don’t anticipate using it much for editing, nano is probably your best choice. If you expect to spend a lot of time using the command-line environment, it’s probably worth learning vim. They have very different design philosophies, so spend some time with each of them to determine which works best for you."

See Apple Computer 2021. Use command-line text editors in Terminal on Mac. Last accessed 2021 08 04 at < https://apple.co/3lwkwcQ >.

[doingarchives]

A lot of quality work here ... my basic sense is that the technical point of the SSH authentication has become embedded in several text revisions with a broader scope. That said, especially with all the effort made to this point - some of the biases and pedagogical issues in these text passages can be fixed as well. Happy to socialize the conversation and lend a hand as needed.

[chendaniely]

Hi @doingarchives I'm helping @emcaulay, one of the newer maintainers for this lesson, and we're both a bit confused about some of the comments since they seem to reference specific parts of the changes but for some reason, we both don't see which specific parts you're pointing to.

One example is from #106 (review)

What we both see is this:

and I can't seem to find a reference to another repo you're referring to which is making the additional fixes a bit hard to track down.

also, since @emcaulay is still working on this issue to incorporate your comments, can we re-open this PR?

[emcaulay]

I'm interested in your comment below, but it wasn't attached to a specific section of the episode, so I was kind of guessing about what you're talking about. I think I agree in principle. I've opened a new issue for this discussion. #110

Not thrilled by reference within a course to material covered in another course. In my view, there are learners in the audience that take specific courses (not sure what percentage - that would be useful data). For these learners, elliptical references can multiply their sense of frustration - something the text here is already anticipating. Also I find this passage to make assumptions about the learning process that are unfortunate (negative outcomes as normal). Again I'm open to assisting on this or socialising the conversation - the reference would work better if the instruction were internalized.

[emcaulay]

@emacauley Thanks for this. Could we agree to consider changing the example address to this: "yourname@domain.name" See ISO 5127 3.1.5.46 (test over on slack).

Yes, I will make those changes now.

[emcaulay]

I don't know where

"If you are stuck here, look at the set up instructions for this lesson. The best way to solve the problem is register for a free Git account".

is in this lesson. It doesn't sound familiar and I've gone through episodes 1 and 2 fairly carefully, but I'll open a new issue for this comment as well. I agree that I don't like the way those two sentences sound and it doesn't make much sense to me.

[doingarchives]

Hello Daniel Awesome. I olli at GitHub as a development environment primarily. There is some confusion (not just on lc-git) but on another lesson I maintain (lc-data-intro-archives). I own some of that because of multiple GitHub accounts. For now, doingarchives on GitHub and Slack are the best channels for the maintenance work. I’ll port the discussions to Slack. Typical issues / pulls involve just a few lines or even words in the lesson. The re considerations of several of the longer sections, and even proposed revisions might be better on Slack and/or a document like Etherpad. Good to be working with you all. Christopher Felker Global open learning, teaching + data about archives and their communities @doingarchives On 2021 04 08, at 18:17 , Daniel Chen ***@***.***> wrote: Hi @doingarchives <https://github.com/doingarchives>! I'm not part of this repo. I just help out the maintainers as a whole without the "big green button" access :) @emcaulay <https://github.com/emcaulay> just asked for some help during the co-working session today I'm hosting to walk her through the github PR interface. I think we both usually see specific comments to specific lines in context so we were both a bit confused and she wanted to make sure I was seeing the same thing. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#106 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AGWQ4PL6RK6BO7DH76PGYLLT3G36ZANCNFSM5BPD3FVA>.

[kekoziar]

All other changes, especially SSH, look good.

[kekoziar]

I don't agree with removing this line

GitHub will ask if you want to add a README.md, license or a .gitignore file. Do not do any of that for now.

If someone includes any files on the remote when it's created, it will cause an error when the local repo is pushed. Since we're setting up learners to succeed at one thing at a time, it's important that the remote repository is completely empty.

[emcaulay]

I think you might not have noticed that I had a line about that above the screenshot, but I think you might be right that the clarity of that sentence is a good repetition. I will add it back in.

This is what I did have in the lesson, but I think the two sentences you point out in this comment are worth keeping indeed.
On line 35 of this lesson, I have:

Clicking New Repository will take you to a creation page with different options. For this workshop, we are not using any of the options available.

[kekoziar]

@emcaulay, Yes, I did lose that sentence.

[tobyhodges]

I am in favour of adding the removed line back in too. Any files added to the GitHub repository when it is created here will cause trouble later in the lesson, when the learner first tries to sync their local and remote versions, and I think the redundancy of including both these sentences is worth it to further guard against that.

[ErinBecker]

Not thrilled by reference within a course to material covered in another course. In my view, there are learners in the audience that take specific courses (not sure what percentage - that would be useful data). For these learners, elliptical references can multiply their sense of frustration - something the text here is already anticipating. Also I find this passage to make assumptions about the learning process that are unfortunate (negative outcomes as normal). Again I'm open to assisting on this or socialising the conversation - the reference would work better if the instruction were internalized.

I don't know for sure for LC workshops, but for SWC workshops, there is a requirement to teach both the shell and git lessons. If that is also the case for LC, I am in favor of cross-referencing lesson materials to encourage learners to make connections with what they have already learned. It may very well be true that there are learners who use the lessons outside of workshops, but our target audience is workshop learners and we should match the materials to that audience. 🙂

[tobyhodges]

This is excellent, and I am delighted to see the coordination between lc-git and swcarpentry/git-novice to make it happen. In my view it is ready to merge, but I have made a couple suggestions of changes for minor improvement. If it is merged here, I will open a PR to propagate the Secure Shell Protocol -> Secure SHell protocol change over on the Software Carpentry lesson too.

[tobyhodges]

I am in favour of adding the removed line back in too. Any files added to the GitHub repository when it is created here will cause trouble later in the lesson, when the learner first tries to sync their local and remote versions, and I think the redundancy of including both these sentences is worth it to further guard against that.

[tobyhodges]

I don't know for sure for LC workshops, but for SWC workshops, there is a requirement to teach both the shell and git lessons. If that is also the case for LC, I am in favor of cross-referencing lesson materials to encourage learners to make connections with what they have already learned.

It is my understanding (from the Library Carpentry Workshop Overview) that an LC workshop must teach at least three of the four core lessons. Technically, that does leave the possibility that instructors might teach the Git lesson without first teaching the Shell lesson, but I do not think that would be likely to happen, especially if the language added in this PR is merged:

In this lesson we use Git from the Unix Shell. Some previous experience with the shell is expected, but is not mandatory.

[ErinBecker]

Thank you @emcaulay for the work that you've put into this PR. I've reviewed, along with @tobyhodges, @chendaniely, and @kekoziar, and this looks great! Although there are some unresolved comments in the conversation thread, these are outside of the scope of this PR and can be dealt with in separate issues/PRs. Since the security issue that this PR is addressing is due to land on the 13th, I'm going to go ahead and merge this (with thanks!!) to keep the lessons from breaking. Happy to continue some of these broader conversations in other threads.

[doingarchives]

@emcaulay Kindly see Slack for additional discussion. Not seeing connection between Update link syntax throughout lesson ISS#112 ... looking for markdown reference(s).