data-lessons/library-git-deprecated

Git Intro for Librarians NOW MOVED > https://github.com/LibraryCarpentry/lc-git

library-git-deprecated's Issues

Sentence structure (extra words)

Being a bit persnickety, I know we don't read these out but I'm thinking of those that read the lessons to learn.

1. In "Getting Started," "Tracking files in Git" section, starts with...if we opted for colourised output, we can see that the file... we don't need the "got." Sentence reads better without it.

2. In "Sharing your work," "Pushing Changes" section, start with "say we are very forgetful and have already forgotten what we changes we have made. We don't need the second "we."

backup when git not working

Sometimes things doesn't work on an attendees laptop: the software is installed incorrectly, they've installed the wrong thing, it all just unfathomably doesn't work.

Now, peer programming is great from a pedagogical point of view, so "work with someone else" is a good option. But prompted by @weaverbel, we should consider adding a backup to our Instructor Notes.

Can this lesson just take the same approach as data-lessons/library-shell-DEPRECATED#53?

Typo in the text

After the part of committing the first changes in Git there is the following sentence:
"We do have a problem know though." I think that it is meant that there is a problem now.

Develop learning objectives for git lesson

It will be helpful to have a defined set of learning objectives for the lesson.

Review exercise

I think it would be good to think about uses for Git - maybe for versioning Library Guides or exhibition copy or whatever. But practical uses. The existing review exercise is not that great because most people haven't grasped enough of the workflow to have ideas though most people can relate Commit to Save, for example.
We want people to come away with an understanding of why they would bother, which is why we need a compelling exercise.
Library guides might be good as , in some cases, good text has been chucked away by a Track Changes edit cycle, whereas with Git, any lost text could always be brought back.
Also the strength of Git is that nothing is ever lost. That you can stuff up and recover from that by reverting to an older version.

Check links to point to new Gitter rooms

Just noticed with the git discussion and looking at the lessons. The pages of the git lesson need a review checking the Gitter link(s) to reflect the new chat room setup for Library Carpentry. This is an issue for all the lessons as well. I post to the Git lesson since it is the one first up in the lesson-dev room.

Lesson structure

There are obviously plenty of tutorials out there already that start along the lines of

• git init
• git add/remove
• git push/pull

But as mention in #7 (comment) this isn't really how people are likely to use git/github. Probably start with something more along the lines of:

• Create a repo
• Edit a file and push changes (with git diff, git status etc)
• Add/Remove
• Fork someone else's code (going on to PRs?)
• ...

Move content over to gh-pages

Looks like @cmacdonell has set up a gh-pages branch using the SWC/DC template but it currently needs filling in, so here's an issue to track progress on that.

SQL for libraries (github repo) has already made a start on this, for reference.

• Move lesson content to _episodes
• Move content from handout.md into the appropriate place
• Tidy up the formatting in line with guidance

How could ANDS use GIt?

We are workshopping this today - ideas please!

Handout

This lesson might benefit from making a handout of reference materials.

To do this add detail of commands/terminology under the keypoints headers for each lesson: for example, https://github.com/data-lessons/library-data-intro/blob/gh-pages/_episodes/04-regular-expressions.md. This effectively then builds a handout at - for example http://data-lessons.github.io/library-data-intro/reference/ - which can be printed out in advance of the session (librarians love handouts!)

Make sure you make a note of this in your Instructor Notes #49

All in One Page Not Working

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

https://data-lessons.github.io/library-git/aio/

Review/Recommend scenarios illustrating use of GitHub/Git in Library context

I've drafted the following Library GitHub/Git use scenario (based on real life as well as the Audiences view https://software-carpentry.org/audience/), do folks think this works? Suggestions for more?

You are a local librarian looking to create a crowdsourcing project allowing people to tag historical photographs. Your team looks at a few other crowdsourcing projects on the web and even though they all appear unique to each institution, they seem to have similar functionality and structure. Rather than build your version from scratch, you wish there was a way to just copy that version, and modify it to reflect your project. You notice the GitHub icon at the bottom of these pages.

Related to #7

Disperse "06-Git in Libraries" into "05-Review" and "01-Info" and deleting

Good points here under http://data-lessons.github.io/library-git/06-git-in-libraries/. Suggest some could be turned into scenarios for under 01-intro and the rest make up a revised Review activity focussed on considering the contexts in which Git and GitHub could be useful for Libraries.

Clean-up Setup Page

Need to enhance the setup page so it includes more complete instructions so that it can stand alone. References to other weeks without links too confusing. http://data-lessons.github.io/library-git/setup/ @alexandermendes wanna have a go?

Why librarians should care about Git?

As @drjwbaker has mentioned I think one of the things that could be 'bulked out' in this lesson is an explanation of why GitHub matters for librarians. I am happy to do a 'Why you should care about GitHub' section. I think the main things to focus on are:

• research data management - with all three considered broadly. Librarians are already and will increasingly contribute to this.
• collaboration - related to the above. Git can facilitate collaboration and open up new workflows in a bunch of ways.
• Publishing - also related to the above. GitHub offers a new way of 'publishing'. Librarians need to think about how to deal with this. Helping both the 'production' and 'consumption' side of things. citing code?
• a gateway to loads of tools, resources and support. A huge amount of open source software is on GitHub if librarians want to use this software it is helpful if they know how to interact with Git.

Are there other things that could be included?

requiered git pull when created README.md during repository init on github

It would be good to mention that when people init repository on github, they should not choose to create README.md. If they do, they will not be able to push from local repository without pulling changes first.

"Real world" examples

I've been briefly trying to figure out a scenario where we can demonstrate the collaborative side of things, as part of the fork, branch, PR workflow.

So, to setup for the lesson the instructor creates a repo containing a basic jekyll site, just generated from a template or whatever. The index of this repo will iterate _pages (an empty folder to begin with) and list links to, or pull metadata from, all contained files.

Everyone forks this repo, creates a branch (from gh-pages) and adds a new file to _pages. This file could be named firstname_surname.md, with some basic yaml metadata at the top and whatever else they want to write (a couple of lines about me? my favourite book? etc.)

Changes are pushed and PRs are submitted.

The instructor pulls them all in (hopefully not too much of a hassle, how large do the classes tend to be anyway?). We shouldn't get any merge conflicts, unless two people have the same name.

We now have a basic "real world" example where everyone can see their contributions in the commit history, along with a website showing whatever it is we choose to show. Perhaps this is getting into complicated territory but it would be nice to find a way to make this workshop style tutorial different from the plethora of git/GitHub tutorials already out there!

Using nano command in Git Bash

In the part about the git commands there is given an example to make changes to the test file using nano. I installed Git Bash, but then I got the message that the nano command was not found. I would suggest for Windows users to tell them how to install nano or otherwise tell them to change the testfile in Notepad (++).

Add contributor and maintainer info

Add maintainers to the README and contributors to AUTHORS, as per data-lessons/librarycarpentry#8

Not correctly linked image

In Git_lesson.md under the title "What is Git?" there is a link tot a comic, but it doesn't work. If I go to the link (given in the raw format) it works properly though.

no git clone

This lesson starts with git init and sets a remote and pushes to GitHub. It does not mention git clone at all.

I use git for my work everyday, git init is something I have done only a handful of times, but I git clone most days. If our aim is to teach people how to share code and interact with GitHub, it makes sense to at least mention clone.

Personally, when I teach git workshops I mention git init and provide the workflow outline similar to the SWC lesson, but skip over it to a more common everyday workflow: create a repository on GitHub (with a readme), clone the repository, make changes, push. These seems to lower the cognitive load about init and setting remotes, which is hard to understand in the abstract. Starting with a clone seems to be a much more realistic workflow for using GitHub since it is what you will encounter in everyday work, collaborating with others or switching between computers.

Thoughts on possible approaches:

1. add a git clone section at the end of the current demo to show how you would work with the test repo going forward (and reinforce / review git pull / add / commit / push).
2. use the first git init lesson to explain git and working locally, but instead of creating a blank repo on GitHub and adding a remote, start a new demo that creates a GitHub repo with readme and git clone.

Instructor Notes

This lesson has out of date Instructor Notes http://data-lessons.github.io/library-git/guide/. These are helpful for passing on tips to potential instructors. See http://data-lessons.github.io/library-data-intro/guide/ for an example of how this might be done.

Add authors to AUTHORS file

We now have a workflow for releasing citable versions of our lessons (with DOIs) every 6 months via Zenodo. This makes our more discoverable and sustainable and ensures that everyone involved gets the credit they deserve. For more on this work see data-lessons/librarycarpentry#5

In order to make this happen we need to make one crucial change: all AUTHORS files need to change so that they list names of contributors in the following format:

James Allen
James Baker
Piotr Banaszkiewicz
Erin Becker

@jt14den will run a script that that strips names from lesson logs and edit AUTHORS across all Library Carpentry repos.

When this is actioned (hopefully, soon!), lesson maintainers are asked to eyeball the AUTHORS file to see if anyone obvious is missing (for example, people who contributed to discussions but didn't edit any lessons). Note: template developers are credited in this process; this is in line with Software Carpentry best practice.

In the future, lesson maintainers are encouraged to ensure that those who contribute to lessons are added manually to AUTHORS files (encourage contributors to do it so they see where and how we give credit!)

Building static sites using GitHub pages in second hour

• I think the original schedule for this session is unrealistic for most groups. A smaller group with more experience on command line tools may cruise through the first hour but I think there will usually be issues with installation etc that need to be addressed.
• A good starting point for doing something on building websites with GitHub pages would be Building a static website with Jekyll and GitHub Pages a Programming Historian lesson. This lesson probably covers too much but might be a useful further resource.

A mistake in the README.md file

The "Citation" section of mentioned Git Intro for Librarians lesson but the link is for Shell Lessons for Librarians.

Here is how it is currently posted:
Citation
Please cite as:
Library Carpentry. Git Intro for Librarians. June 2016. http://data-lessons.github.io/library-shell/.

Here is how it should be:
Citation
Please cite as:
Library Carpentry. "Git Intro for Librarians." June 2016, http://data-lessons.github.io/library-git/.

I edited the file with the proposed change.

Consistency of lessons titles.

The lessons' titles on the schedule of the main page of "Git Intro for Librarians" lesson needs to be consistent. Here is the page: http://data-lessons.github.io/library-git/

Maintaining the lesson

I am happy to volunteer to maintain this - anyone else keen?

Typo in the text

In the Getting Started episode under the Using Git section there is this sentence, " The best way to get to learn GIT language - which consists of a number of verbs, or commands, e.g. add, commit precended by the word Git...."

Precended should be preceded.

GitHub pages episode

As raised in #7 we can add a GitHub pages episode towards the end. We probably want to keep this as simple as possible but it could be a useful exercise to help people become more comfortable with branching and pushing etc.

Gitlab not mentioned

In the lesson there is a title called Git v. GitHub vs. GitLab, but the last one is not mentioned in the following text, so it is a bit confusing that it is mentioned in the title.