1 Working with source control {#scm}
2 ===========================
6 # Avoiding source control entirely {#scm_avoid}
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/).
15 # Basic usage {#scm_basic}
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
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
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!
31 - If working with a fork, use `git push origin develop` periodically to
32 store your changes on GitHub.
34 # Feature branches {#scm_feature}
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
43 to facilitate
this process.
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
58 When you are done and want to merge into `develop`
do
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