Page Comparison

How to work with the ACME code base.

1. Read the Development Big Picture page.  Note in particular the recommended philosophy of working with branches is different than what you may be used to.  
2. Sign up for a free account at http://github.com
3. Github account:  Add your github user name to the "About Me" section in your Confluence profile.  Then Email James Foucar (jgfouca@sandia.gov) and ask to be added to the ACME private organization on github.  Include your Confluence account name so he can verify you're a member of ACME.   
4. input data account:  Get an account on both the ACME "inputdata" server and the public CESM "inputdata" server (if you don't already have access):
   1. Instructions for /wiki/spaces/WORKFLOW/pages/7998629
   2. For the CESM inputdata server, use any of the following
      1. Use the guest account:  user id:  guestuser   password:  friendly
      2. OR Register as a CESM user.  Register here first: http://www.cesm.ucar.edu/models/register/register.html   (if that doesn't work, try  http://www.cesm.ucar.edu/models/current.html and then Acquiring the CESM code).  Note that this it the unrestricted public release.  
      3. OR If you have access to the restricted CESM development repository, that account will also work for the inputdata repo.
   3. cache your username/password on each machine you use with either of the 2 methods below:
      
      1. using a web browser: Go to https://acme-svn2.ornl.gov/acme-repo/ and https://svn-ccsm-inputdata.cgd.ucar.edu/trunk/inputdata/ and enter your xcams and cesm username and password
      2. using svn directly: type 'svn ls https://acme-svn2.ornl.gov/acme-repo/', then enter your XCAMS user name and password at the prompt. If asked whether you would like to "store password unencrypted?", answer "yes'. Then type 'svn ls https://svn-ccsm-inputdata.cgd.ucar.edu/trunk/inputdata/' and enter the needed username and password.

   
   

   ---

   
   

5. Log on to the platform on which you want to do ACME development. See Computational Resources for a description of available machines.
6.  Install an ssh key from that platform to your github account.  See these instructions and note you can skip step 2 if you already have an ssh key on your machine.
   (NOTE: you can skip the next four steps below by running this script https://gist.github.com/douglasjacobsen/3ea4421c0d8ae8c460b0 )
7. Set up your git environment with these commands:
   

   1. git config --global user.name “First Last”

   2. git config --global user.email “user@lab.gov”  (NOTE: use the email you registered on github.com)

   3. git config --global push.default nothing
   4. git config --global core.editor ${EDITOR}   (vim, emacs, etc.)

   5. git config --global color.ui true

   6. git config --global core.autocrlf false
   7. git config --global core.safecrlf false
   8. git config --global pull.ff only
8. Clone the repository to your local account. This will create a directory called "ACME" with the code.  
   git clone git@github.com:ACME-Climate/ACME.git  
9.  Get the source code for MPAS-based modelssubmodules needed by ACME.  change directory to ACME and do:  
   git submodule update --init
10. Clone the repository hooks:  while still in the ACME directory, do: 
    rm -rf .git/hooks; git clone git@github.com:ACME-Climate/ACME-Hooks.git .git/hooks
11. Setup the commit message template: In directory "ACME", do: 
    git config commit.template ${PWD}/.git/hooks/commit.template
12. (optional if using forks (most are not)l) Change the remote from origin to "ACME" to allow easier use of other peoples forks: 
    git remote rename origin ACME
13. (Optional but recommended) Download and source git-prompt to add branch information to your bash prompt.
14. (Optional but recommended) Download and source git-completion.bash to enable tab completion of git commands.
    
    You are ready to start developing! 
    
    
    

    ---

      
15. Make sure there is a JIRA task associated with your code development.  This will be referenced in the commit message.
16. By default, you will be on the "master" branch.  For new development you may want to either (1) create your own branch off of "master", or (2) work on a branch that someone else has already created.
    1. To switch your working tree (local copy) to a pre-existing branch:
       1. look for remote branch names:  git branch -r  or see Existing and Planned Tags and Branches
       2. Run:  git checkout --track <remote branchname>
       3. Ensure your checkout is up to date:    git pull --ff-only
       4. Update MPAS components: git submodule update --init
    2. To create a new topic branch for your development:  The following command assumes you are on the master branch, change 'master' to the branch name you're using if it's different
       1. Ensure your clone is up to date:  git pull --ff-only origin master
          1. If an error is encountered when pulling, talk to an integrator about fixing it
       2. Create your topic branch for your development:  FOLLOW THE ACME BRANCH NAME CONVENTIONS!
       3. create the branch in your repository, branching from master:   git branch <branchname> master
       4. switch your working tree (local copy) to this branch:   git checkout <branchname>
       5. Update MPAS Components: git submodule update --init
       6. To ensure you are working on the correct branch, run "git branch" which will show all your local branches and list a "*" by the branch in your current working tree.
17. Before doing any development, create baselines for any tests you will be using to verify your changes, and place these baselines in a directory you will use to test your branch. At a minimum, this should be baselines for the acme_developer test suite. This is a good idea even if you are not making answer-changing code modifications, since the baseline files for the master branch can be changed by other merges while you are working. For information on generating baselines, see Testing.
18. If you have any issues compiling or running the code, check with the POC for the platform you are using:  Configuration Management.   The POC is responsible for ensuring ACME tests can run on supported platforms and will be knowledgeable about system specific quirks and features.    
19. Start editing your code and commit changes to your local repository. (e.g., after making changes, do: git add <files> ; git commit).  See Commit message template for how to make a commit message.  We no longer use ChangeLog so commit messages are important.
20. Once you have committed at least one change locally, push your branch to the main repository.  You may not be done but this will allow others to follow and contribute to your work.
    1. git push origin <branchname>  Anytime you run "git push" you need to be extremely careful that you know exactly what git is going to do (use --dry-run if you're not sure).  
    2. Never run git push without specifying a branchname.  This ensures you push the correct branch (and not the master branch)
21. Add tests for your new feature following ACME unit test framework (NOT YET IMPLEMENTED)
22. Periodically run "Developers Test Suite" including your new tests and confirm All Tests Pass.  Basic instructions for running the Developers Test Suite are in Testing
    
    

    ---

    
    
    
23. When you are finished with your development, push your branch to github (see step 18)
24. Run the "Developers Test Suite" if it is supported on your platform.  See Configuration Management table and Testing instructions.  Make sure all tests pass. 
25. Go to our github site and make a Pull Request.  See Development Reference#Submittingapullrequest for details.
    NOTE: Do NOT merge your own branch.  DO NOT PUSH THE MERGE PULL REQUEST button.

Remaining steps will be led by an ACME Integrator.  Your feature is not done until the Integrator moves your changes to the "master" branch.

Further and more detailed instructions can be found in the Development Reference.
 

If you're new to git, see the Git Tutorial page