generated from carpentries/workbench-template-rmd
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
0 parents
commit f1e2417
Showing
15 changed files
with
688 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
|
||
:::::::::::::::::::::::::::::::::::::::::::::::::: | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
:::::::::::::::::::::::::::::::::::::::::::::::::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
:::::::::::::::::::::::::::::::::::::::::::::::::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
Oops, something went wrong.