Merge pull request #452 from katrinleinweber/mentoring

Add assorted fixes, rephrasing & improvement suggestions

CONTRIBUTING.md

@@ -140,13 +140,13 @@ You can also [reach us by email][contact].
 [dc-lessons]: http://datacarpentry.org/lessons/
 [dc-site]: http://datacarpentry.org/
 [discuss-list]: http://lists.software-carpentry.org/listinfo/discuss
-[github]: http://github.com
+[github]: https://github.com
 [github-flow]: https://guides.github.com/introduction/flow/
 [github-join]: https://github.com/join
 [how-contribute]: https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github
 [new-issue]: https://github.com/swcarpentry/git-novice/issues/new
 [issues]: https://github.com/swcarpentry/git-novice/issues/
 [repo]: https://github.com/swcarpentry/git-novice/
 [swc-issues]: https://github.com/issues?q=user%3Aswcarpentry
-[swc-lessons]: http://software-carpentry.org/lessons/
-[swc-site]: http://software-carpentry.org/
+[swc-lessons]: https://software-carpentry.org/lessons/
+[swc-site]: https://software-carpentry.org/

LICENSE.md

@@ -26,7 +26,7 @@ Under the following terms:
 * **Attribution**---You must give appropriate credit (mentioning that
   your work is derived from work that is Copyright © Software
   Carpentry and, where practical, linking to
-  http://software-carpentry.org/), provide a [link to the
+  https://software-carpentry.org/), provide a [link to the
   license][cc-by-human], and indicate if changes were made. You may do
   so in any reasonable manner, but not in any way that suggests the
   licensor endorses you or your use.
@@ -78,6 +78,6 @@ are registered trademarks of [NumFOCUS][numfocus].
 
 [cc-by-human]: https://creativecommons.org/licenses/by/4.0/
 [cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode
-[mit-license]: http://opensource.org/licenses/mit-license.html
-[numfocus]: http://numfocus.org/
-[osi]: http://opensource.org
+[mit-license]: https://opensource.org/licenses/mit-license.html
+[numfocus]: https://numfocus.org/
+[osi]: https://opensource.org

README.md

@@ -12,6 +12,6 @@ Maintainers:
 * [Ivan Gonzalez][gonzalez_ivan]
 * [Daisie Huang][huang_daisie]
 
-[gonzalez_ivan]: http://software-carpentry.org/team/#gonzalez_ivan
-[huang_daisie]: http://software-carpentry.org/team/#huang_daisie
+[gonzalez_ivan]: https://software-carpentry.org/team/#gonzalez_ivan
+[huang_daisie]: https://software-carpentry.org/team/#huang_daisie
 [lesson-example]: https://swcarpentry.github.io/lesson-example

_episodes/01-basics.md

@@ -60,7 +60,7 @@ across different computers facilitating collaboration among different people.
 > Automated version control systems are nothing new.
 > Tools like RCS, CVS, or Subversion have been around since the early 1980s and are used by many large companies.
 > However, many of these are now becoming considered as legacy systems due to various limitations in their capabilities.
-> In particular, the more modern systems, such as Git and [Mercurial](http://swcarpentry.github.io/hg-novice/)
+> In particular, the more modern systems, such as Git and [Mercurial](https://swcarpentry.github.io/hg-novice/)
 > are *distributed*, meaning that they do not need a centralized server to host the repository.
 > These modern systems also include powerful merging tools that make it possible for multiple authors to work within
 > the same files concurrently.

_episodes/02-setup.md

@@ -33,9 +33,9 @@ $ git config --global color.ui "auto"
 
 Please use your own name and email address instead of Dracula's. This user name and email will be associated with your subsequent Git activity,
 which means that any changes pushed to
-[GitHub](http://github.com/),
-[BitBucket](http://bitbucket.org/),
-[GitLab](http://gitlab.com/) or
+[GitHub](https://github.com/),
+[BitBucket](https://bitbucket.org/),
+[GitLab](https://gitlab.com/) or
 another Git host server
 in a later lesson will include this information.
 
@@ -71,7 +71,7 @@ in a later lesson will include this information.
 > [on this GitHub page](https://help.github.com/articles/dealing-with-line-endings/).
 {: .callout}
 
-For these lessons, we will be interacting with [GitHub](http://github.com/) and so the email address used should be the same as the one used when setting up your GitHub account. If you are concerned about privacy, please review [GitHub's instructions for keeping your email address private][git-privacy]. 
+For these lessons, we will be interacting with [GitHub](https://github.com/) and so the email address used should be the same as the one used when setting up your GitHub account. If you are concerned about privacy, please review [GitHub's instructions for keeping your email address private][git-privacy]. 
 If you elect to use a private email address with GitHub, then use that same email address for the `user.email` value, e.g. `[email protected]` replacing `username` with your GitHub one. You can change the email address later on by using the `git config` command again.
 
 Dracula also has to set his favorite text editor, following this table:

_episodes/04-changes.md

@@ -8,7 +8,7 @@ questions:
 - "How do I record notes about what changes I made and why?"
 objectives:
 - "Go through the modify-add-commit cycle for one or more files."
-- "Explain where information is stored at each stage of Git commit workflow."
+- "Explain where information is stored at each stage of that cycle."
 - "Distinguish between descriptive and non-descriptive commit messages."
 keypoints:
 - "`git status` shows the status of a repository."
@@ -326,11 +326,10 @@ before actually committing anything. This allows us to commit our
 changes in stages and capture changes in logical portions rather than
 only large batches.
 For example,
-suppose we're adding a few citations to our supervisor's work
-to our thesis.
+suppose we're adding a few citations to relevant research to our thesis.
 We might want to commit those additions,
-and the corresponding addition to the bibliography,
-but *not* commit the work we're doing on the conclusion
+and the corresponding bibliography entries,
+but *not* commit some of our work drafting the conclusion
 (which we haven't finished yet).
 
 To allow for this,
@@ -754,4 +753,4 @@ repository (`git commit`):
 > {: .solution}
 {: .challenge}
 
-[commit-messages]: http://chris.beams.io/posts/git-commit/
+[commit-messages]: https://chris.beams.io/posts/git-commit/

_episodes/05-history.md

@@ -303,7 +303,7 @@ recent commit (`HEAD~1`), which is commit `f22b25e`:
 So, to put it all together,
 here's how Git works in cartoon form:
 
-![http://figshare.com/articles/How_Git_works_a_cartoon/1328266](../fig/git_staging.svg)
+![https://figshare.com/articles/How_Git_works_a_cartoon/1328266](../fig/git_staging.svg)
 
 > ## Simplifying the Common Case
 >

_episodes/07-github.md

@@ -21,8 +21,8 @@ only thing missing is to copy changes from one repository to another.
 Systems like Git allow us to move work between any two repositories.  In
 practice, though, it's easiest to use one copy as a central hub, and to keep it
 on the web rather than on someone's laptop.  Most programmers use hosting
-services like [GitHub](http://github.com), [BitBucket](http://bitbucket.org) or
-[GitLab](http://gitlab.com/) to hold those master copies; we'll explore the pros
+services like [GitHub](https://github.com), [BitBucket](https://bitbucket.org) or
+[GitLab](https://gitlab.com/) to hold those master copies; we'll explore the pros
 and cons of this in the final section of this lesson.
 
 Let's start by sharing the changes we've made to our current project with the
@@ -161,7 +161,7 @@ Branch master set up to track remote branch master from origin.
 >
 > in the terminal, before you run `git push`.  Despite the name, [git uses
 > `SSH_ASKPASS` for all credential
-> entry](http://git-scm.com/docs/gitcredentials#_requesting_credentials), so
+> entry](https://git-scm.com/docs/gitcredentials#_requesting_credentials), so
 > you may want to unset `SSH_ASKPASS` whether you are using git via SSH or
 > https.
 >

_episodes/09-conflict.md

@@ -12,8 +12,8 @@ keypoints:
 - "The version control system does not allow people to overwrite each other's changes blindly, but highlights conflicts so that they can be resolved."
 ---
 
-As soon as people can work in parallel, it's likely someone's going to step on someone
-else's toes.  This will even happen with a single person: if we are working on
+As soon as people can work in parallel, they'll likely step on each other's
+toes.  This will even happen with a single person: if we are working on
 a piece of software on both our laptop and a server in the lab, we could make
 different changes to each copy.  Version control helps us manage these
 [conflicts]({{ page.root }}/reference/#conflicts) by giving us tools to
@@ -178,7 +178,7 @@ This line added to Wolfman's copy
 ~~~
 {: .output}
 
-Our change—the one in `HEAD`—is preceded by `<<<<<<<`.
+Our change is preceded by `<<<<<<< HEAD`.
 Git has then inserted `=======` as a separator between the conflicting changes
 and marked the end of the content downloaded from GitHub with `>>>>>>>`.
 (The string of letters and digits after that marker

_episodes/10-open.md

@@ -46,12 +46,12 @@ though,
 the process looks like this:
 
 *   The data that the scientist collects is stored in an open access repository
-    like [figshare](http://figshare.com/) or
-    [Zenodo](http://zenodo.org), possibly as soon as it's collected,
+    like [figshare](https://figshare.com/) or
+    [Zenodo](https://zenodo.org), possibly as soon as it's collected,
     and given its own
     [Digital Object Identifier](https://en.wikipedia.org/wiki/Digital_object_identifier) (DOI).
     Or the data was already published and is stored in
-    [Dryad](http://datadryad.org/).
+    [Dryad](https://datadryad.org/).
 *   The scientist creates a new repository on GitHub to hold her work.
 *   As she does her analysis,
     she pushes changes to her scripts
@@ -60,7 +60,7 @@ the process looks like this:
     She also uses the repository for her paper;
     that repository is then the hub for collaboration with her colleagues.
 *   When she's happy with the state of her paper,
-    she posts a version to [arXiv](http://arxiv.org/)
+    she posts a version to [arXiv](https://arxiv.org/)
     or some other preprint server
     to invite feedback from peers.
 *   Based on that feedback,
@@ -73,10 +73,10 @@ the process looks like this:
 
 This open model accelerates discovery:
 the more open work is,
-[the more widely it is cited and re-used](http://dx.doi.org/10.1371/journal.pone.0000308).
+[the more widely it is cited and re-used](https://doi.org/10.1371/journal.pone.0000308).
 However,
 people who want to work this way need to make some decisions
-about what exactly "open" means and how to do it. You can find more on the different aspects of Open Science in [this book](http://link.springer.com/book/10.1007/978-3-319-00026-8).
+about what exactly "open" means and how to do it. You can find more on the different aspects of Open Science in [this book](https://link.springer.com/book/10.1007/978-3-319-00026-8).
 
 This is one of the (many) reasons we teach version control.
 When used diligently,
@@ -96,10 +96,9 @@ by acting as a shareable electronic lab notebook for computational work:
 
 > ## Making Code Citable
 >
-> [This short guide](https://guides.github.com/activities/citable-code/) from GitHub
-> explains how to create a Digital Object Identifier (DOI) for your code,
-> your papers,
-> or anything else hosted in a version control repository.
+> Anything that is hosted in a version control repository (data, code, papers, 
+> etc.) can be turned into a citable object. You'll learn how to do this in
+> [lesson 12: Citation]({{ page.root }}/12-citation/).
 {: .callout}
 
 > ## How Reproducible Is My Work?
@@ -113,21 +112,11 @@ by acting as a shareable electronic lab notebook for computational work:
 > ## How to Find an Appropriate Data Repository?
 >
 > Surf the internet for a couple of minutes and check out the data repositories
-> mentioned above: [Figshare](http://figshare.com/), [Zenodo](http://zenodo.org),
-> [Dryad](http://datadryad.org/). Depending on your field of research, you might
+> mentioned above: [Figshare](https://figshare.com/), [Zenodo](https://zenodo.org),
+> [Dryad](https://datadryad.org/). Depending on your field of research, you might
 > find community-recognized repositories that are well-known in your field.
 > You might also find useful [these data repositories recommended by Nature](
-> http://www.nature.com/sdata/data-policies/repositories).
+> https://www.nature.com/sdata/data-policies/repositories).
 > Discuss with your neighbor which data repository you might want to
 > approach for your current project and explain why.
 {: .challenge}
-
-> ## Can I Also Publish Code?
->
-> There are many new ways to publish code and to make it citable. One
-> way is described [on the homepage of GitHub itself](
-> https://guides.github.com/activities/citable-code/).
-> Basically it's a combination of GitHub (where the code is) and Zenodo (the
-> repository creating the DOI). Read through this page while being aware
-> that this is only one of many ways to making your code citable.
-{: .challenge}

_episodes/11-licensing.md

@@ -27,7 +27,7 @@ A license solves this problem by granting rights to others (the
 licensees) that they would otherwise not have. What rights are being
 granted under which conditions differs, often only slightly, from one
 license to another. In practice, a few licenses are by far the most
-popular, and [choosealicense.com](http://choosealicense.com/) will
+popular, and [choosealicense.com](https://choosealicense.com/) will
 help you find a common license that suits your needs.  Important
 considerations include:
 
@@ -41,8 +41,8 @@ Choosing a license that is in common use makes life easier for
 contributors and users, because they are more likely to already be
 familiar with the license and don't have to wade through a bunch of
 jargon to decide if they're ok with it.  The [Open Source
-Initiative](http://opensource.org/licenses) and [Free Software
-Foundation](http://www.gnu.org/licenses/license-list.html) both
+Initiative](https://opensource.org/licenses) and [Free Software
+Foundation](https://www.gnu.org/licenses/license-list.html) both
 maintain lists of licenses which are good choices.
 
 [This article][software-licensing] provides an excellent overview of
@@ -77,4 +77,4 @@ thus need to be asked for approval once a license is chosen.
 > - [EtherPad](https://github.com/ether/etherpad-lite), a real-time collaborative editor
 {: .challenge}
 
-[software-licensing]: http://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1002598
+[software-licensing]: https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1002598

_episodes/12-citation.md

@@ -44,3 +44,15 @@ July 2013.
 }
 ~~~
 {: .source}
+
+More detailed advice, and other ways to make your code citable  can be found in
+[here](https://www.software.ac.uk/how-cite-and-describe-software) and in:
+
+>  Smith AM, Katz DS, Niemeyer KE, FORCE11 Software Citation Working Group. 
+>  (2016) Software citation principles. [PeerJ Computer Science 2:e86](https://peerj.com/articles/cs-86/) https://doi.org/10.7717/peerj-cs.86
+ 
+There is also an [`@software{…`](https://www.google.de/search?q=git+citation+%22%40software%7B%22) 
+[BibTeX](https://www.ctan.org/pkg/bibtex) entry type in case
+no "umbrella" citation like a paper or book exists for the project you want to
+make citable.
+

_episodes/13-hosting.md

@@ -29,8 +29,8 @@ but requires more time and effort to set up than either the option above or the
 option below.
 
 The third option is to use a public hosting service like
-[GitHub](http://github.com), [GitLab](http://gitlab.com),
-[BitBucket](http://bitbucket.org), or [SourceForge](http://sourceforge.net).
+[GitHub](https://github.com), [GitLab](https://gitlab.com),
+[BitBucket](https://bitbucket.org), or [SourceForge](http://sourceforge.net).
 Each of these services provides a web interface that enables people to create,
 view, and edit their code repositories.  These services also provide
 communication and project management tools including issue tracking, wiki pages,
@@ -45,6 +45,11 @@ GitHub]({{ swc_github }}) where you can find the [source for this
 page]({{page.root}}/_episodes/13-hosting.md).
 Anyone with a GitHub account can suggest changes to this text.
 
+GitHub repositories can also be assigned DOIs, [by connecting its releases to
+Zenodo](https://guides.github.com/activities/citable-code/). For example,
+[`10.5281/zenodo.57467`](https://zenodo.org/record/57467) is the DOI that has
+been "minted" for this introduction to Git.
+
 Using large, well-established services can also help you quickly take advantage
 of powerful tools.  One such tool, continuous integration (CI), can
 automatically run software builds and tests whenever code is committed or pull
@@ -78,5 +83,5 @@ open source projects, and are also available for private repositories for a fee.
 >
 > Does your institution have a repository or repositories that you can
 > use to share your papers, data and software? How do institutional repositories
-> differ from services like [arXiV](http://arxiv.org/), [figshare](http://figshare.com/) and [GitHub](http://github.com/)?
+> differ from services like [arXiV](https://arxiv.org/), [figshare](https://figshare.com/), [GitHub](https://github.com/) or [GitLab](https://about.gitlab.com/)?
 {: .challenge}

_episodes/14-supplemental-rstudio.md

@@ -33,12 +33,12 @@ our computer, we'll choose "existing directory":
 >
 > Although we're not going to use it here, there should be a "version control"
 > option on this menu. That is what you would click on if you wanted to
-> create a project on your computer by cloning a repository from github.
+> create a project on your computer by cloning a repository from GitHub.
 > If that option is not present, it probably means that RStudio doesn't know
 > where your Git executable is. See
 > [this page](https://stat545-ubc.github.io/git03_rstudio-meet-git.html)
 > for some debugging advice. Even if you have Git installed, you may need
-> to accept the XCode license if you are using MacOSX.
+> to accept the XCode license if you are using macOS.
 {: .callout}
 
 Next, RStudio will ask which existing directory we want to use. Click "browse"
@@ -91,8 +91,8 @@ If we click on "history", we can see a pretty graphical version of what
 
 ![](../fig/RStudio_screenshot_viewhistory.png)
 
-RStudio creates some files that is uses to keep track of your project. You
-generally don't want to track these, so adding them to your .gitignore file
+RStudio creates some files that it uses to keep track of your project. You
+generally don't want to track these, so adding them to your `.gitignore` file
 is a good idea:
 
 ![](../fig/RStudio_screenshot_gitignore.png)

_extras/guide.md

@@ -288,7 +288,7 @@ web-hosted private repositories.
 [git-it-electron]: https://github.com/jlord/git-it-electron
 [git-parable]: http://tom.preston-werner.com/2009/05/19/the-git-parable.html
 [github]: https://github.com/
-[github-gui]: http://git-scm.com/downloads/guis
+[github-gui]: https://git-scm.com/downloads/guis
 [github-line-endings]: https://help.github.com/articles/dealing-with-line-endings/#platform-all
 [github-privacy]: https://help.github.com/articles/keeping-your-email-address-private/
 [repos-in-repos]: https://github.com/swcarpentry/git-novice/issues/272

_includes/all_figures.html

@@ -16,7 +16,7 @@
 <hr/>
 <p><img alt="Git Checkout" src="../fig/git-checkout.svg" /></p>
 <hr/>
-<p><img alt="http://figshare.com/articles/How_Git_works_a_cartoon/1328266" src="../fig/git_staging.svg" /></p>
+<p><img alt="https://figshare.com/articles/How_Git_works_a_cartoon/1328266" src="../fig/git_staging.svg" /></p>
 <hr/>
 <p><img alt="" src="../fig/RStudio_screenshot_newproject.png" /></p>
 <hr/>