IMP logo
IMP Manual  for IMP version 2.16.0
scm.md
1 Working with source control {#scm}
2 ===========================
3 
4 [TOC]
5 
6 # Avoiding source control entirely {#scm_avoid}
7 
8 We strongly recommend the use of source control (ideally git). However, if
9 you have only a small change to make to %IMP, such as a bug fix, and do
10 not want to use source control, we'd rather get the fix than not! In this
11 case, make a patch and [email it to us](https://integrativemodeling.org/contact.html) or,
12 better yet, open up an [issue on GitHub](https://github.com/salilab/imp/issues)
13 with the patch as a [gist](https://gist.github.com/).
14 
15 # Basic usage {#scm_basic}
16 
17 See [the FAQ](@ref faq_git) for some resources on using git. For basic
18 development of %IMP, work in the default `develop` branch and do the
19 following:
20 
21  - Periodically run `git pull` to get latest 'upstream' changes into your
22  copy (if you [made a fork](@ref devsetup), you should also periodically
23  [sync it with the main repository](https://help.github.com/articles/syncing-a-fork/).
24  `git imp update` is similar but will also show you any new entries from
25  the changelog.
26 
27  - Commit any changes you make frequently, e.g. `git add <list_of_new_files>`
28  and `git commit -a -m "<description of my recent changes>"`.
29  git makes it easy to undo, but only if you commit things to git!
30 
31  - If working with a fork, use `git push origin develop` periodically to
32  store your changes on GitHub.
33 
34 # Feature branches {#scm_feature}
35 
36 If you are making a large change that, for example, touches a bunch of files
37 or will not necessarily be finished before you would like to work on something
38 else %IMP related, use a `feature` branch. Doing this also allows you to share
39 the change with other people, before it is
40 committed into `develop` (e.g. to get them to check it doesn't break anything,
41 or to test it as you are developing it). We provide tools, based on
42 [git flow](http://nvie.com/posts/a-successful-git-branching-model/),
43 to facilitate this process.
44 
45  1. Run `git imp feature start feature_name` to start a new feature branch.
46  This will open up up an editor where you can write a `%README.md` for
47  the feature. The contents of the `%README.md` will be used to describe
48  the branch as well as the final commit message for the branch when
49  it is merged into `develop`.
50  2. Work on the branch as above (`git commit`, `git add` etc.)
51  3. Use `git imp feature publish feature_name` to publish the branch to
52  GitHub, if desired. (If you want to use a branch someone else published in
53  this way, use `git imp feature track feature_name`.)
54  4. Use `git imp feature pull origin` to get any new changes.
55  5. Use `git push origin feature/feature_name` to push any new changes to
56  the branch to GitHub.
57 
58 When you are done and want to merge into `develop` do
59 
60  1. `git imp feature finish <feature_name>` to merge into `develop`,
61  using the contents of the `%README.md` as the commit message.
62  The `%README.md` file is removed before this is done.
63  2. `git push origin :feature/<feature_name>` to remove the branch from
64  the GitHub repository if you shared it