IC Documentation Release 0.1
Total Page:16
File Type:pdf, Size:1020Kb
IC Documentation Release 0.1 IC team Sep 27, 2021 Contents 1 How to contribute to IC 3 1.1 Prepare github..............................................3 1.2 Prepare your repositories.........................................3 1.3 Use a higher-level git interface......................................3 1.4 History philosophy............................................4 1.5 Workflow summary...........................................4 1.6 Workflow in detail............................................5 1.7 Testing..................................................8 1.8 Style guide................................................9 2 How to use notebooks in IC 11 2.1 The problem with notebooks....................................... 11 2.2 Workflow................................................. 11 3 Core modules 13 4 Indices and tables 15 i ii IC Documentation, Release 0.1 Contents: Contents 1 IC Documentation, Release 0.1 2 Contents CHAPTER 1 How to contribute to IC 1.1 Prepare github • Get a github account if you do not already have one. • Upload your SSH key, if you have not already done so. 1.2 Prepare your repositories TODO • Fork the IC repository • Clone your fork • set nextic as upstream 1.3 Use a higher-level git interface Do yourself a favour, and use magit to interact with git: it’s the best git UI on the planet. Even if you don’t use or dislike Emacs, use magit, and think of Emacs as the GUI framework in which magit is written. You will enjoy and learn to understand git much more if you use magit. [Editor’s note: Seriously, I tried to find something to recommend for those who don’t use Emacs. It wasted a lot of my time, and I came to the conclusion that recommending anything else would be a waste of your time. Just use magit.] To make the magit experience even better, use helm. 3 IC Documentation, Release 0.1 1.4 History philosophy In the words of Ben Sandofsky: Treat public history as immutable, atomic, and easy to follow. Treat private history as disposable and malleable. The intended workflow is: 1. Create a private branch off a public branch. 2. Regularly commit your work to this private branch. 3. Once your code is perfect, clean up its history. 4. Merge the cleaned-up branch back into the public branch. • In IC, step 4 is done by the IC administators after the work has been reviewed and approved, so you don’t have to worry about this step for now. • The history that appears in your local clone (your private history) is there entirely for your benefit. As such, it is malleable and disposable, and you can modify it however and whenever you like. • The history that appears in the central nextic repository serves as a clean, high-level description of the evolution of the project, where – it should be easy to find where and when something was changed, added, removed, where bugs were introduded (perhaps using tools such as git bisect), – a high-level description of the changes should be available. As such, the central history should – be linear, – contain very descriptive commit messages describing and documenting the changes. • The commits that appear in your fork on github can serve a number of purposes: – A place from which you submit pull requests, asking for your contribution to be incorporated into the main repository. (The commits that appear in pull requests should therefore conform to the high standards required by the main history: clean, linear (usually squashed) and documented with descriptive commit messages.) – Triggers of travis builds, checking that your work builds and passes all the tests in a clean environment. – Sharing your work with other developers and collaborating on development with others before submitting a pull request. 1.5 Workflow summary 1. Create a topic branch starting at upstream/master in your local repo. 2. Make numerous checkpoint commits to your topic branch. 3. Write tests for the code you write. 4. Push the topic branch to your github fork (origin) whenever you want feedback from Travis. 5. In preparation for making a pull request (PR), squash the checkpoint commits into a smaller number of logically self-contained commits with descriptive, high-level commit messages. Try to make each commit (and its diff) tell a story that will be easily understood by the reviewers. 6. Fetch (whatever you do, do not pull) upstream/master into your local repository.. 4 Chapter 1. How to contribute to IC IC Documentation, Release 0.1 7. Rebase your topic branch onto upstream/master. 8. Push the branch to origin. 9. a pull request (PR) from your github page. 10. Wait for the PR to be approved and merged. 11. Fetch upstream/master into your local repo. 12. Delete your topic branch, both locally and in your fork. 13. GOTO 1 1.6 Workflow in detail In what follows, the commands required to achieve the effect will be given in two styles (eventually; initially the git CLIs are likely to be TODOs). 1. magit 2. git command line interface (CLI) In the case of magit you should type the instructions in some magit buffer inside Emacs. If no such buffer is visible, create the magit status buffer with M-x magit-status. This last command must be given in some buffer linked to a file or directory inside the relevant git repository. Magit buffers can usually be closed with q. Emacs commands in general can be interrupted with C-g. In the case of the git CLI, you should type the commands in a shell whose working directory is inside there relevant git repository. 1. Before starting some new work, make sure that you have the most recent IC code. • magit: f e upstream RET – f opens the magit fetching popup – e allows you to specify the remote from which you would elike to fetch – upstream specifies that you want to fetch from the central nextic repository. (This assumes that you have already added upstream as a remote pointing at nextic/IC in your local repository) • git CLI: git fetch upstream 2. Create a topic branch. In the following examples replace ‘topic’ with whatever name you want to give to your branch. The name sohuld be meaningful to you and identify the work that you are doing. You may end up having multiple topic branches in existence simultaneously, so picking good names will make life easier for you. • magit: b c upstream/master RET topic RET – b opens the magit branch popup – c creates and checks out a new branch – upstream/master is the location from which you want to branch off – topic is the name of your new branch • git CLI: git checkout -b topic upstream/master 1.6. Workflow in detail 5 IC Documentation, Release 0.1 Magit will walk you through these steps interactively. Helm, if you’ve installed it, will improve the interactive experience. If you make a mistake magit will help you avoid digging yourself into a deeper hole. With the git CLI you are on your own. 3. Create plenty of checkpoint commits while you are working. Frequent checkpoint commits ensure that, if you ever get yourself into a complete mess, you can get out of it cheaply by reverting to a recent sensible state. This is how to do a local commit • magit: – M-x magit-status (or your keybinding, possibly C-x g) Opens the magit status buffer, showing you (among other things) * which files have been modified since the last commit * which files have been deleted since the last commit * which files exist but are not registered in the repository The most useful keys inside this buffer are * s: stage - include this in the next commit * u: unstage - undo a previous stage * n: next - move to the next interesting location * p: previous - move to the previous interesting location * c: commit - start the commit process * d: diff - open the magit diff popup So, you should specify what you want to be included in the commit by staging it. Then proceed with the commit with c, at which point a commit message buffer should appear, with self-explanatory comments inside it. In short, write a commit message and then perform the commit with C-c C-c. When you get around to creating a pull request, you should squash (see below) your checkpoint com- mit messages into a smaller number of coherent, clean, commits with descriptive commit messages describing your work. The purpose of the checkpoint commit messages is to make authoring the pull request commit messages as easy as possible. • git CLI: TODO 4. Make sure that the code you contribute is adequately tested. See below. 5. Whenever you want to see whether your current code builds and passes all the required tests in a clean environ- ment, commit (described above) and push to your fork (origin). • magit: – The first time in a new branch: P p origin RET – Thereafter: P p P opens the magit push popup. Once there, p pushes to the remote which needs to be set once for each branch. • git CLI: TODO 6. Once you have achieved something worth incorporating into the main repository, it’s time to make a pull request (PR). Usually your pull request should consist of a smaller number of commits than you originally made during development, each with a carefully written, high-level, descriptive commit message describing your work. The commit message of a single-commit PR is taken as the default PR description text. If your PR contains more than one commit, you should create a description of the whole collection in the GitHub PR interface. 6 Chapter 1. How to contribute to IC IC Documentation, Release 0.1 You should squash your numerous checkpoint commits to make cleaner PR commits.