librarycarpentry / lc-git Goto Github PK

From a beginner's perspective, we've mentioned metadata only once in the text of this lesson. I think the term could be used a lot earlier in this lesson.

In addition, the second Key Point notes that there is a 2-stage commit process. As a beginner, I'm looking for stages distinctly identified as such in the lesson to verify my understanding. We could clearly identify those stages as distinct by using headers like, "Committing to Changes, Stage 1", etc. in the organization of the page.

In Episode 3: Pushing Changes

Do not use the word upstream to represent the transmission of the .git metadata the remote repository.

The flag -u hasn’t been explained in the context of setting a upstream branch or tracking branch. The usage of the word ‘upstream’ would make more sense if the -u is explained along with it’s long form flag --set-upstream.

Another reason, to avoid using this term is because the name upstream is sometimes used to track remotes other than the origin.

The excerpt from the episode 3 that I refer to is copied below:

When we do a git push, we will see Git ‘pushing’ changes upstream to GitHub. 
Because our file is very small, this won’t take long but if we had made a lot of 
changes or were adding a very large repository, we might have to wait a little 
longer. We can check where we’re at with git status.

Thanks for contributing! If this contribution is for instructor training, please send an email to [email protected] with a link to this contribution so we can record your progress. You’ve completed your contribution step for instructor checkout just by submitting this contribution.

If this issue is about a specific episode within a lesson, please provide its link or filename.

Please keep in mind that lesson maintainers are volunteers and it may be some time before they can respond to your contribution. Although not all contributions can be incorporated into the lesson materials, we appreciate your time and effort to improve the curriculum. If you have any questions about the lesson maintenance process or would like to volunteer your time as a contribution reviewer, please contact The Carpentries Team at [email protected].

This lesson is listed as core, but is still listed as beta. What still remains to move this lesson to stable and then publish?

This lesson has now been migrated to the Library Carpentry organisation. Work should happen on THIS repo.

All the issues that need resolving are still at the old location, however: https://github.com/data-lessons/library-git-DEPRECATED/issues

Find issues to resolve there and fix them here.

There are a few really key important modules currently missing from this lesson -- perhaps the most important is the git config. The current lessons would fail because learners can't make a commit without first telling git who they are. I propose the following 6 lessons:

1. what is git and how its different from github

• should also include how git works -- like what's the staging area, WHY IT MATTERS (people don't get why they can't add then commit)

2. setting git up (git config) -- this needs to happen before getting started with git. can't commit changes when you don't have a name or email associated with the commit

3. making a git repository (currently called 'setting up')

• Git: init, add, commit

4. time traveling with git (going back to a previous commit, going back to the current commit) -- exploring history

• Git: checkout

5. sharing your work (title from existing lesson)

• GitHub: making a repository
• Git: push origin master

6. contributing to other people's work (forking, cloning the new repo in your namespace, making a pull requests)

• GitHub: fork + PRs, permissions
• Git: clone repo

I am working on adding them over at: https://github.com/VickySteeves/lc-git

Ensure we are not mixing up terms (e.g., Git & GitHub) or including jargon.

We need to gather diverse examples for lessons. Ideally this would be from all types of libraries or examples that could apply to all libraries.

On https://librarycarpentry.org/lc-git/reference.html under Useful library GitHub repositories the link to pyMarc is now located here https://gitlab.com/pymarc/pymarc in gitlab.

History of this: data-lessons/library-git-DEPRECATED#58
and this too: data-lessons/library-git-DEPRECATED#7
and this: data-lessons/library-git-DEPRECATED#34
and this: data-lessons/library-git-DEPRECATED#42

Add brief descriptions of why the links listed in the Quick Reference (https://librarycarpentry.org/lc-git//reference.html ) > Useful library github repositories section are useful to libraries? For instance, here is an example where the Code4Lib community used GitHub for a petition in support of Chris Bourg https://github.com/code4lib/c4l18-keynote-statement.

Should some of the examples be removed and/or replaced?

There are some definition problems for newbies n the section that reads:
We can also see the commit message ‘Add index.md’, which we added by adding the -m flag to git commit. The commit message is used to record a short, descriptive, and specific summary of what we did to help us remember later on without having to look at the actual changes. If we just run git commit without the -m option, Git will launch nano (or whatever other editor we configured as core.editor) so that we can write a longer message.

The "flag" term doesn't mean what I might be used to. A flag is something that changes what a default action might ordinarily be, as is implied here. Flag needs to be defined for non-technical types. In most of my experience (usually email), it refers to a mark made for later action.
"Message" is ambiguous. From a non-technical perspective, I can't tell if that means I just created a text message in the index.md file or something else (maybe like doing some sort of vi editor). Based on what I've been told it's sort of like commenting out to document program changes.
-m means that your merging the old file with the new changes you made, though you're not saving the merged file.

@doingarchives recently raised the issue that the text editor configuration in this lesson is problematic. I would like feedback from the community about this topic.

@chendaniely, please note this is an issue that might benefit from broader discussion across multiple lessons.

CONTRIBUTING.md refers to lc-date-intro rather than lc-git.

"She notices the GitHub icon at the bottom of one of the projects she likes, but clicking on the link just brings her to a confusing directory of files and oddly labeled buttons such as “Fork”. "

I don't know what the icon looks like. Please include a picture of it.

Mentioned as part of pull request #106 , there are two sentences that don't seem helpful that the reviewer noticed, but reviewer did not note which episode or line.

The sentences are:

""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".

I can't find those sentences in the lesson right now, so I'll have to go back and find them and evaluate what the purpose of those sentences are and if they can be removed or revised.

The following sentence needs a re-write.
" Increasingly though they can are being used for all kinds of files across research and academic collaborations."

It may be helpful to add information about GitLab, Bitbucket, Sourceforge, Gitea, Gitee and other similar git collaboration software, since many people may need to use these and the workflow is similar.

In "We can create a new git repository either by using GitHub’s web interface, or via the command line. " We need a link to the GitHub’s web interface.

So, the phrase "staging area" implies that it's a needed step for this lesson. The information under that section is really a "note" or a "tip". Using either of these terms would be much clearer.

This section begins with kind of a negative and also arrogant tone, and might be worth revising.

One of the main barriers to getting started with Git is the language. Although some of the language used in Git is
fairly self-explanatory, other terms are not so clear. The best way to get to learn the language - which consists of a
number of verbs such as add, commit and push (preceded by the word 'git') - is by using it, which is what we will be doing during this lesson. These commands will be explained as we proceed from setting up a new version-controlled project to publishing our own website.

In a number of instances, installing Git onto a Mac computer requires the download of XCode, a free Mac application. The need for that application is not documented and it probably should be. The XCode application is 5GB, which requires a lot of time to download. There's no instruction about how to deal with XCode anywhere. In addition, though it's not a problem associated with Carpentry, the SurgeForce Git application looks a little scary because the package requires a couple of leaps of faith: you have to disable an important security feature on your computer, and you have to believe that the incorrect operating system name (it says it's Maverick and the latest OS is High Sierra) given to the latest version is not going to harm your system. Please document this somewhere.

The GitHub default branch is now main not master. However, creating a git repository locally will be by default in a master branch. This creates a problem when we connect the local and remote branch in "Sharing Your Work", Episode 3: https://librarycarpentry.org/lc-git/03-sharing/index.html.

Solution: adopt what GitHub suggests after you create a repository there. This means changing the image in Sharing Your Work from starting with "…or push an existing repository from the command line" under Connecting your local repository to the GitHub repository to the new instructions:

git remote add origin https://github.com/some-librarian/hello-world.git
git branch -M main
git push -u origin main

Possibly include the text of the code rather than the image so it's more copy and pasteable. We also need to then change all references from master to main in the lesson. @scottcpeterson and I are teaching this on 1/29 and can come back with a PR.

Following up on discussions from #42 and #41 :

The LC-Git lesson needs to help participants 1. install git and 2. configure git.

Currently we have very basic instructions for both on the setup page.

SWC does install centrally (in the workshop template, set up for all parts of the two day workshop), then covers configuration during the Git lesson in Setting up git.

It seems like we need:

• more details about installing on the setup page, since (I think) LC-Git is intended to be more stand alone (i.e. we don't know if people will be running all the other lessons at the same time as part of a SWC style bootcamp).
• details about configuration, possibly as a new episode mirroring SWC Setting up git, added to LC-Git's current Getting started with git page, or expanding on the current LC-Git setup page

Configure your git setup under “Prerequisites” in this lesson returns a 404.

Because we don't teach the concept of branching elsewhere in the lesson, and because GitHub can generate pages from master as well by now, I think we can simplify the "gh-pages branch" section in episode 5.

Maybe by switching simply gh-pages to master, or by referring completely to the official tutorial on pages.GitHub.com? What do you think?

Many librarians could get benefits from git without ever touching the command line. Teaching github first would show people how to be immediately productive with git and allow them to learn the concepts without the added cognitive load of dealing with the command line.

Reach out to instructors/helpers that have taught Git for their feedback/notes (scan workshop data https://github.com/LibraryCarpentry/librarycarpentry.github.io/blob/master/_data/workshops.yml for Git instructors). Create a new folder in repo called "instructor_notes" where these notes can be submitted to. Deadline to receive feedback, March 29.

As mentioned by @tobyhodges in the review of PR #106, there is a standard practice for linking and providing references at the end of each Markdown file. Adopting this across this lesson would improve its usability and clarity.

https://librarycarpentry.org/lc-git//03-sharing/index.html

The Pushing Changes section shows the output of git push -u origin master but also has an extra prompt and a git status included:

PS C:\github\hello-world> git status
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working tree clean

I think this should be removed from the output block entirely, since git status following the push is covered just a couple lines down, and has the same exact output, all formatted correctly.

From a beginner's perspective, once I've created the file on a Mac you cannot easily find it. The file is not where you think it is if you try to browse to it. It's more foolproof to have users use Finder to search for it, then have them open it in a text editor. It would be useful to include XCode as a text editor here, because it becomes the default for SOME Mac users.

This seems to result from https://github.com/LibraryCarpentry/lc-git/blame/gh-pages/_extras/guide.md#L25-L93. The missing links should be added to https://github.com/LibraryCarpentry/lc-git/blob/gh-pages/_includes/links.md and pushed to #51.

Per discussion on the Carpentries Slack #General channel, there is a known problem with outdated Windows OpenSSH. There is a known bug. (See details here: PowerShell/Win32-OpenSSH#966).

It will be useful to add an alert to instructors in the instructor notes so that troubleshooting is better supported.

GitHub is changing requirements for command line interaction on August 13, 2021. While practicing for an upcoming workshop, I found using the instructions under Pushing Changes in Lesson 3 prompted am email Deprecation Notice email from GitHub which may disrupt the flow of a lesson. I recommend addressing the new requirements outlined here https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/

This lesson has now been migrated to the Library Carpentry organisation. All updates and new issues should happen on THIS repo.

All the issues that need resolving are still at the old location, however: https://github.com/data-lessons/library-git-DEPRECATED/issues

Find issues to resolve there and fix them here.

On the Git lesson intro page, there's a bit of first person language (like "Be Patient with Me" and "This isn't my full time job"). This seems like it is supposed to be from the Instructor's point of view, but it doesn't seem generic enough to apply to any Instructor. I'd suggest adapting this to be more general.

I'm parking this suggestion from a public library about how we might tailor the training to fit their needs:

For example, you could do the git lesson, but use planning a story time
as the project. That could all be done in plain text, what songs you
sing, what books you read, any rhymes, etc. Then you could show how you
can track changes and share and fork repos etc. That would take these
skills out of the realm of only useful to geeks and help show how all
librarians can benefit.

I think that commands: ls, touch need to be defined. Non-linux/unix users may not be familiar with these.

If your Maintainer team has decided not to participate in the June 2019 lesson release, please close this issue.

To have this lesson included in the 18 June 2019 release, please confirm that the following items are true:

• Example code chunks run as expected
• Challenges / exercises run as expected
• Challenge / exercise solutions are correct
• Call out boxes (exercises, discussions, tips, etc) render correctly
• A schedule appears on the lesson homepage (e.g. not “00:00”)
• Each episode includes learning objectives
• Each episode includes questions
• Each episode includes key points
• Setup instructions are up-to-date, correct, clear, and complete
• File structure is clean (e.g. delete deprecated files, insure filenames are consistent)
• Some Instructor notes are provided => yes, but: #32 cc @drjwbaker
• Lesson links work as expected

When all checkboxes above are completed, this lesson will be added to the 18 June lesson release. Please leave a comment on carpentries/lesson-infrastructure#26 or contact Erin Becker with questions ([email protected]).

The Contributing Guidelines section on "Where to Contribute" points to the data-lessons repository, which has been deprecated: https://github.com/LibraryCarpentry/lc-git/blob/gh-pages/CONTRIBUTING.md#where-to-contribute
I can fix this if it's a matter of just not having those links updated, but wanted to make sure that this section of the guidelines is no longer correct.

I'm confused by the discussion of Git when the lesson is supposed to be on Github. The background does not provide me with insights needed to work better using Github. After telling us that they different, it doesn't help to keep conflating them either.

Reference.md's Further Reading lists some text-only resources.

Since before that GitHub Desktop had an interactive tutorial repo, and recently GitHub's Learning Labs started. Do you have experience with those? Are they useful to be added to our reference?

IMHO, their official character and interactivity make them almost must-haves.

As suggested by @doingarchives, consider changing our image filenaming technique.

Specifically, would using ISO 5127:2017 be more effective for organizing our images that support our lessons.

I would prefer that if we adopt this standard that we do so across all Carpentries lessons.

Recommended by @chendaniely for discussion.

One of the critical practices that enables collaboration on a project in git is feature branching. At this time, branching is first mentioned in the Github Page episode, but is not prefaced by an introduction or conceptual explanation.

It's likely to be helpful if a visual reference to a feature branch, the purpose behind creating one, and the steps to create a branch off of master or develop are introduced ahead of the Pages episode. Creating a standalone episode about branching, before diving into Pages, could be considered as well.

An example feature branch diagram (using master, rather than develop):

Although discussing something like gitflow is too heavyweight, familiarizing learners with creating and merging simple feature branches will enable them to work on a small team concurrently without stepping on each other's toes.

While teaching this lesson, I realized two commands can help the learners onboard to git better:

1. git diff - to view unstaged changes
2. git log - to view commit history

We can add it to the Getting Started episode.

I'm happy to make the contribution if we're good with the suggestion.

On the Git Lesson Instructors Guide the link to keeping your email address private is not working.

It is: https://help.github.com/en/articles/about-commit-email-addresses

Some possible alternatives:
https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address
https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/blocking-command-line-pushes-that-expose-your-personal-email-address

Under the Episodes Menu: 'All in One (Beta)' link returns a 404

https://librarycarpentry.github.io/lc-git/

Migrated from data-lessons/library-git-DEPRECATED#60

I didn't necessarily have the same result in the Sharing your work > Pushing changes section.
https://librarycarpentry.org/lc-git/03-sharing/index.html

I tried
git push -u origin master
and got:

To https://github.com/libcce/hello-world.git
! [rejected] master -> master (fetch first)
error: failed to push some refs to 'https://github.com/libcce/hello-world.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

Do others get the same response?

@katrinleinweber @dheles @tpatwood @EvaSeidlmayer

Comparison with Dropbox to relate to participants with a tool that they are familiar with.

• https://michaelstepner.com/blog/git-vs-dropbox/
• https://www.dataschool.io/github-is-just-dropbox-for-git/
• Consider one other tool/scenario as well.

=> Google Slide