source commit: 785e2b4

01-basics.md

@@ -0,0 +1,129 @@
+---
+title: Automated Version Control
+teaching: 5
+exercises: 0
+---
+
+::::::::::::::::::::::::::::::::::::::: objectives
+
+- Understand the benefits of an automated version control system.
+- Understand the basics of how automated version control systems work.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::: questions
+
+- What is version control and why should I use it?
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+We'll start by exploring how version control can be used
+to keep track of what one person did and when.
+Even if you aren't collaborating with other people,
+automated version control is much better than this situation:
+
+!["notFinal.doc" by Jorge Cham, <https://www.phdcomics.com>](fig/phd101212s.png){alt='Comic: a PhD student sends "FINAL.doc" to their supervisor, but after several increasingly intense and frustrating rounds of comments and revisions they end up with a file named "FINAL_rev.22.comments49.corrections.10.#@$%WHYDIDCOMETOGRADSCHOOL????.doc"'}
+
+We've all been in this situation before: it seems unnecessary to have
+multiple nearly-identical versions of the same document. Some word
+processors let us deal with this a little better, such as Microsoft
+Word's
+[Track Changes](https://support.office.com/en-us/article/Track-changes-in-Word-197ba630-0f5f-4a8e-9a77-3712475e806a),
+Google Docs' [version history](https://support.google.com/docs/answer/190843?hl=en), or
+LibreOffice's [Recording and Displaying Changes](https://help.libreoffice.org/Common/Recording_and_Displaying_Changes).
+
+Version control systems start with a base version of the document and
+then record changes you make each step of the way. You can
+think of it as a recording of your progress: you can rewind to start at the base
+document and play back each change you made, eventually arriving at your
+more recent version.
+
+![](fig/play-changes.svg){alt='Changes Are Saved Sequentially'}
+
+Once you think of changes as separate from the document itself, you
+can then think about "playing back" different sets of changes on the base document, ultimately
+resulting in different versions of that document. For example, two users can make independent
+sets of changes on the same document.
+
+![](fig/versions.svg){alt='Different Versions Can be Saved'}
+
+Unless multiple users make changes to the same section of the document - a 
+[conflict](../learners/reference.md#conflict) - you can
+incorporate two sets of changes into the same base document.
+
+![](fig/merge.svg){alt='Multiple Versions Can be Merged'}
+
+A version control system is a tool that keeps track of these changes for us,
+effectively creating different versions of our files. It allows us to decide
+which changes will be made to the next version (each record of these changes is
+called a [commit](../learners/reference.md#commit)), and keeps useful metadata
+about them. The complete history of commits for a particular project and their
+metadata make up a [repository](../learners/reference.md#repository).
+Repositories can be kept in sync across different computers, facilitating
+collaboration among different people.
+
+:::::::::::::::::::::::::::::::::::::::::  callout
+
+## The Long History of Version Control Systems
+
+Automated version control systems are nothing new.
+Tools like [RCS](https://en.wikipedia.org/wiki/Revision_Control_System), [CVS](https://en.wikipedia.org/wiki/Concurrent_Versions_System), or [Subversion](https://en.wikipedia.org/wiki/Apache_Subversion) have been around since the early 1980s and are used by
+many large companies.
+However, many of these are now considered legacy systems (i.e., outdated) due to various
+limitations in their capabilities.
+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 on
+the same files concurrently.
+
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::  challenge
+
+## Paper Writing
+
+- Imagine you drafted an excellent paragraph for a paper you are writing, but later ruin
+  it. How would you retrieve the *excellent* version of your conclusion? Is it even possible?
+
+- Imagine you have 5 co-authors. How would you manage the changes and comments
+  they make to your paper?  If you use LibreOffice Writer or Microsoft Word, what happens if
+  you accept changes made using the `Track Changes` option? Do you have a
+  history of those changes?
+
+:::::::::::::::  solution
+
+## Solution
+
+- Recovering the excellent version is only possible if you created a copy
+  of the old version of the paper. The danger of losing good versions
+  often leads to the problematic workflow illustrated in the PhD Comics
+  cartoon at the top of this page.
+
+- Collaborative writing with traditional word processors is cumbersome.
+  Either every collaborator has to work on a document sequentially
+  (slowing down the process of writing), or you have to send out a
+  version to all collaborators and manually merge their comments into
+  your document. The 'track changes' or 'record changes' option can
+  highlight changes for you and simplifies merging, but as soon as you
+  accept changes you will lose their history. You will then no longer
+  know who suggested that change, why it was suggested, or when it was
+  merged into the rest of the document. Even online word processors like
+  Google Docs or Microsoft Office Online do not fully resolve these
+  problems.
+
+
+
+:::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::: keypoints
+
+- Version control is like an unlimited 'undo'.
+- Version control also allows many people to work in parallel.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+

03-collaborative-git-centralized.md

@@ -0,0 +1,63 @@
+
+---
+title: Collaborative Version Control - Centralized
+teaching: 50
+exercises: 60
+---
+
+:::::::::::::::::::::::::::::::::::::::: questions
+
+- How can I use version control to collaborate with internal collaborators?
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+
+::::::::::::::::::::::::::::::::::::::: objectives
+
+- Understand the basics of collaborative version control with git and Github
+- Understand the centralized workflow
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+::: instructor
+Teaching is done as a pair of instructors. 
+Instructor A acts as the owner of the repository, instructor B as a collaborator (internal or external).
+
+First we show the centralized workflow all in the browser using Github: 
+
+* instructor A creates an issue (for example create ‘sum’ function)
+* instructor B picks up the issue  
+* Instructor B creates a new branch (good to do this explicitly) 
+* Instructor B does some reviewable changes (a simple ‘sum’ function) 
+* Instructor B opens a new pull request. 
+* Instructor A reviews and approves the PR. 
+* Instructor B merges the pull request. 
+* Use Github repo’s insights -> network to visualize what just happened 
+
+:::
+
+::::::::::::::::::::::::::::::::::::::: challenge
+
+#### Exercise: Working as a project collaborator (in pairs):
+- PERSON A: Create an issue in the repository
+- PERSON B: Clone this repository to your system
+- PERSON B: Create a new branch
+- PERSON B: Make the changes requested in the issue
+- PERSON B: Push the changes to the remote repository on GitHub
+- PERSON B: Submit a Pull Request, refer to the issue (e.g. "Closes #1")
+- PERSON A: Review the Pull Request
+- PERSON B: Address the comments
+- PERSON A: Approve the Pull Request
+- PERSON B: Merge the Pull Request
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::::: solution
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+
+:::::::::::::::::::::::::::::::::::::::: keypoints
+* Git and Github are superpowerful, not just for version control, but as tools for collaborative development
+* Do code reviews and be constructive in them!
+* Use centralized flow for internal collaborations
+::::::::::::::::::::::::::::::::::::::::::::::::::

03-collaborative-git-distributed.md

@@ -0,0 +1,58 @@
+
+---
+title: Collaborative Version Control - Distributed
+teaching: 10
+exercises: 60
+---
+
+:::::::::::::::::::::::::::::::::::::::: questions
+
+- How can I use version control to collaborate with external collaborators?
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+
+::::::::::::::::::::::::::::::::::::::: objectives
+
+- Understand distributed workflow and when to use it
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+::: instructor
+Teaching is done as a pair of instructors. 
+Instructor A acts as the owner of the repository, instructor B as a collaborator (internal or external).
+
+Now we show distributed workflow. All in the browser using Github:
+
+* Instructor A removes instructor B
+* Instructor B now submits an issue
+* Instructor A responds to issue asking instructor B to pick it up
+* Instructor B forks repo, does some changes, and submits PR
+* Instructor A reviews the changes
+* Instructor B implements the changes
+* Instructor A merges the pull request
+* Use Github repo’s insights -> network to visualize what just happened 
+:::
+
+::::::::::::::::::::::::::::::::::::::: challenge
+
+### Exercise: Working as an external contributor (in pairs)
+
+- PERSON A: Create an issue in Person B's repository
+- PERSON A: Fork the repository to their own (= Person A's) account
+- PERSON A: Clone the repository, make changes, push them back to the fork
+- PERSON A: Submit a Pull Request from the fork to the original repository
+- PERSON B: Make a change in the original repository in the same place as person A's proposed changes
+- PERSON A: Solve the merge conflict in the Pull Request
+- PERSON B: Review/Approve the Pull Request
+- PERSON B: merge the Pull Request 
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::::: solution
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+
+:::::::::::::::::::::::::::::::::::::::: keypoints
+* Use distributed flow for external collaborations
+::::::::::::::::::::::::::::::::::::::::::::::::::

CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+---
+title: "Contributor Code of Conduct"
+---
+
+As contributors and maintainers of this project,
+we pledge to follow the [The Carpentries Code of Conduct][coc].
+
+Instances of abusive, harassing, or otherwise unacceptable behavior
+may be reported by following our [reporting guidelines][coc-reporting].
+
+
+[coc-reporting]: https://docs.carpentries.org/topic_folders/policies/incident-reporting.html
+[coc]: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html

LICENSE.md

@@ -0,0 +1,79 @@
+---
+title: "Licenses"
+---
+
+## Instructional Material
+
+All Carpentries (Software Carpentry, Data Carpentry, and Library Carpentry)
+instructional material is made available under the [Creative Commons
+Attribution license][cc-by-human]. The following is a human-readable summary of
+(and not a substitute for) the [full legal text of the CC BY 4.0
+license][cc-by-legal].
+
+You are free:
+
+- to **Share**---copy and redistribute the material in any medium or format
+- to **Adapt**---remix, transform, and build upon the material
+
+for any purpose, even commercially.
+
+The licensor cannot revoke these freedoms as long as you follow the license
+terms.
+
+Under the following terms:
+
+- **Attribution**---You must give appropriate credit (mentioning that your work
+  is derived from work that is Copyright (c) The Carpentries and, where
+  practical, linking to <https://carpentries.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.
+
+- **No additional restrictions**---You may not apply legal terms or
+  technological measures that legally restrict others from doing anything the
+  license permits.  With the understanding that:
+
+Notices:
+
+* You do not have to comply with the license for elements of the material in
+  the public domain or where your use is permitted by an applicable exception
+  or limitation.
+* No warranties are given. The license may not give you all of the permissions
+  necessary for your intended use. For example, other rights such as publicity,
+  privacy, or moral rights may limit how you use the material.
+
+## Software
+
+Except where otherwise noted, the example programs and other software provided
+by The Carpentries are made available under the [OSI][osi]-approved [MIT
+license][mit-license].
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Trademark
+
+"The Carpentries", "Software Carpentry", "Data Carpentry", and "Library
+Carpentry" and their respective logos are registered trademarks of [Community
+Initiatives][ci].
+
+[cc-by-human]: https://creativecommons.org/licenses/by/4.0/
+[cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode
+[mit-license]: https://opensource.org/licenses/mit-license.html
+[ci]: https://communityin.org/
+[osi]: https://opensource.org