Checklists¶

Make use of Git¶

[ ] Make your project version controlled by initialising a Git repository in its directory using git init.
[ ] Add and commit all your files to the repository using git add . then git commit.
[ ] Continue to add and commit changes as your project progresses. Stage the changes in specific files to be committed with git add filename, and add messages to your commits.
- [ ] Each commit should make one simple change.
- [ ] No generated files committed.
- [ ] Commit messages are meaningful, with a ~50 character summary at the top.
- [ ] Commit messages are in the present tense and imperative.
[ ] Develop new features on their own branches, which you can create via git checkout -b branch_name and switch between via git checkout branch_name.
- [ ] Branches have informative names.
- [ ] Master branch is kept clean.
- [ ] Each branch has a single purpose and only changes related to that purpose are made on it.
[ ] Once features are complete merge their branches into the master branch by switching to the feature branch and running git merge master.
- [ ] Merge other’s changes into your work frequently.
- [ ] When dealing with merge conflicts make sure you fully understand both versions before trying to resolve them.

Contribute to someone else’s project¶

[ ] Clone their project’s repository from GitHub git clone repository_url.
[ ] Make and commit changes.
[ ] Push your changes to you GitHub version of the project.
[ ] Make use of issues to discuss possible changes to a project.
[ ] Make pull requests on GitHub to share your work.
- [ ] Clearly explain the changes you’ve made and why in your pull request.

Make sure that your data is version controlled¶

[ ] If your projects involves data, check whether Git LFS, git-annex, or DataLad fit your needs for version controlling it.
[ ] Share data together with your project to help others reproduce your results.

What to learn next¶

Look into best practice for writing good quality code (for example, good naming conventions, informative comments, modular code structure). Many such skills are either also applicable for using version control well, for example, for writing good commit messages, or make using version control easier by keeping changes neat and localised.

Definitions/glossary¶

Add: Command used to add files to the staging area. Allows the user to specify which files or directories to include in the next commit.
Branch: A parallel version of a repository. Although it is contained within the same repository it allows you to develop it separately and then merge changes back into the ‘live’ repository or with other branches when appropriate.
Checkout: Git command to switch to a specific file, branch, or commit. Allows you to activate older versions of files or commits or switch between active branches.
Clone: Copy of an existing Git repository, normally from some remote location to your local environment. When you clone a repo you copy its entire history as well as all branches.
Commit: Snapshot of project history. A commit can be made after changes of a single file or a range of files and directories.
Commit message: A message the user can attach to a commit to explain what it contains.
Git: Version control system that GitHub is built around. It is a widely used open source distributed version control system developed by the author of Linux.
GitHub: An online hosting and version control service which centres around the version control software Git. It has a great many features to aid collaboration between users.
HEAD: the latest commit on the branch which is currently checked out
Issues: Bug tracking system for GitHub. Collaborators can use issues to report bugs, request features, or set milestones for projects. Issues are tracked, reported, and closed by collaborators during the development process. They’re a great way of communicating with your team and reporting progress.
Master: the repository’s main branch. Depending on the work flow it is the one people work on or the one where the integration happens.
Merge: The process of combining branches. Changes made on one or more branches are applied to another.
Merge conflict: Incompatibilities between branches being merged.
Pull request: Proposed changes to a remote repository. Collaborators without write access can send a pull request to the administrator with the changes they’ve made to the repo. The administrator can then approve and merge or reject the changes to the main repository. For open source projects pull requests can be sent by anyone that has forked a project.
Push: Sending changes to a remote repo. The remote repository is updated with the changes pushed and now mirrors the local repo.
Repository: Refers to a project folder that is being tracked by Git and containing project files. Also called ‘repo’ for short they can be local as well as hosted on GitHub.
SHA: Unique string of numbers of letters used to identify every commit or node in the repository.
Staged: Changes that will be included in the next commit.

References specific for this chapter¶

1. Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License
2. Creative Commons Attribution License Other useful stuff in this paper, could use their intro as part of the book’s intro
3. Permission to use given by the author (Peter Reimann) 15/12/18
4. Permission given by the author (Tony Yu) 15/12/18
5. Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.
6. creative commons Attribution-NonCommercial-ShareAlike 4.0 International
7. Creative Commons Attribution 2.5 Australia License.
8. Creative Commons Attribution-ShareAlike 3.0 Generic
9. Creative Commons Attribution 4.0 International License
10. Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License
11. Creative Commons license
12. GNU GENERAL PUBLIC LICENSE Version 3
13. “You are granted a limited license to copy anything from this site”
14. creative commons Attribution-NonCommercial-ShareAlike 4.0 International
15. Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
16. Attribution 3.0 Unported (CC BY 3.0)
17. Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
18. Creative Commons Attribution-NonCommercial 2.5 License
19. MIT
20. GNU Free Documentation License
21. Creative Commons Attribution-ShareAlike 4.0 International License
22. Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)
23.Creative Commons Attribution 2.5 Australia License.

Checklists Licensing

The Turing Way