MOOSE-Based Application Development on GitLab MOOSE Team Idaho National Laboratory February 22, 2016
Introduction The intended audience for this talk is developers of INL-hosted, MOOSE-based applications. For information on contributing to the MOOSE framework itself, please see: https://mooseframework.org/static/media/uploads/docs/moose_github.pdf
Introduction This talk is divided into the following sections: Setup Commands you run one time, when getting started. Workflow Commands you ll run every time you develop on GitLab. We will issue all commands in a separate terminal as we go. Please ask questions at any time!
Introduction This talk assumes you: Have access to the INL HPC enclave, and can browse to https://hpcgitlab.inl.gov/groups/idaholab Have uploaded your public SSH key to GitLab, for help on this, please see: http://tinyurl.com/lyrh69p
Introduction We will refer back to this figure several times... GitLab (hpcgitlab.inl.gov) upstream master devel devel review, test, merge Idaholab/<appname> git fetch upstream 1 git checkout devel [ git rebase upstream/devel ] 3 git add [ git commit ] origin 5 Pull Request feature_1729 2 [ git checkout b feature_1729 devel ] username/<appname> feature_1729 4 [ git push origin feature_1729 ] ~/projects/<appname>
Introduction Primary application repository = upstream GitLab (hpcgitlab.inl.gov) upstream master devel devel review, test, merge Idaholab/<appname> git fetch upstream 1 git checkout devel [ git rebase upstream/devel ] 3 git add [ git commit ] origin 5 Pull Request feature_1729 2 [ git checkout b feature_1729 devel ] username/<appname> feature_1729 4 [ git push origin feature_1729 ] ~/projects/<appname>
Introduction Your personal fork of the application repository = origin GitLab (hpcgitlab.inl.gov) upstream master devel devel review, test, merge Idaholab/<appname> git fetch upstream 1 git checkout devel [ git rebase upstream/devel ] 3 git add [ git commit ] origin 5 Pull Request feature_1729 2 [ git checkout b feature_1729 devel ] username/<appname> feature_1729 4 [ git push origin feature_1729 ] ~/projects/<appname>
Introduction The git clone of your fork = /projects/<appname> GitLab (hpcgitlab.inl.gov) upstream master devel devel review, test, merge Idaholab/<appname> git fetch upstream 1 git checkout devel [ git rebase upstream/devel ] 3 git add [ git commit ] origin 5 Pull Request feature_1729 2 [ git checkout b feature_1729 devel ] username/<appname> feature_1729 4 [ git push origin feature_1729 ] ~/projects/<appname>
Setup 1 Introduction 2 Setup 3 Workflow
Setup Step 1: Network, Firewall pass-through setup 1 Setup the connection the hpcgitlab.inl.gov using SOCKS. Edit ~/.ssh/config and make sure you have the following: Host hpcgitlab.inl.gov User <your HPC username here> ProxyCommand nc -x localhost:5555 %h %p 2 Open a secure connection to hpclogin and create a SOCKS proxy $ ssh -D 5555 hpclogin.inl.gov 3 Setup your browser to use SOCKS proxy hostname: localhost port: 5555 4 Vist https://hpcgitlab.inl.gov Note: You will need to uncheck those proxy settings in your browser when you terminate your ssh session.
Setup Step 2: Fork the application repository 1 Go to https://hpcgitlab.inl.gov/idaholab/<appname> 2 Click the Fork repository button.
Setup Step 3: Make a clone of your fork 1 Go to your fork, https://hpcgitlab.inl.gov/username/<appname> 2 On the right side, it should say: Forked from: idaholab/<appname>
Setup Step 3: Make a clone of your fork 3 Copy the SSH URL, you will use it momentarily...
Setup Step 3: Make a clone of your fork 4 Go to a terminal. 5 $ cd ~/projects 6 $ git clone git@hpcgitlab.inl.gov:username/<appname>.git 7 $ cd <appname> 8 $ git config user.name "Your Name" 9 $ git config user.email your email@inl.gov
Setup Step 4: Add a remote for the upstream application repository $ git remote add upstream git@hpcgitlab.inl.gov:idaholab/<appname>.git Adding a remote allows you to stay up-to-date with changes to your application. The name upstream is standard in git parlance, it refers to the central repository for your application. The name origin refers to your personal fork of the application repository.
Setup Step 5: Give other users access to your fork Click Settings
Setup Step 5: Give other users access to your fork Click Members
Setup Step 5: Give other users access to your fork Click Import members
Setup Step 5: Give other users access to your fork Choose the appropriate upstream project
Setup Summary 1 Fork the application repository. 2 Make a clone of your fork. 3 Add a remote for the upstream application repository. 4 Give other users access to your fork.
Workflow 1 Introduction 2 Setup 3 Workflow
Workflow Step 0: Create or pick an issue Visit https://hpcgitlab.inl.gov/idaholab/<appname> Click the green menu button in the top right and select New Issue
Workflow Step 0: Create or pick an issue Enter a title, brief description, and labels for the issue, then click the Submit new issue button.
Workflow Step 1: Pull down the latest changes from upstream Change directories to where you cloned your fork, and run: $ git fetch upstream $ git checkout devel $ git rebase upstream/devel Avoid using git pull commands: Merge commits without proper flags Always do this before starting work to ensure you are up to date.
Workflow Step 1: Pull down the latest changes from upstream GitLab (hpcgitlab.inl.gov) upstream master devel devel review, test, merge Idaholab/<appname> git fetch upstream 1 git checkout devel [ git rebase upstream/devel ] 3 git add [ git commit ] origin 5 Pull Request feature_1729 2 [ git checkout b feature_1729 devel ] username/<appname> feature_1729 4 [ git push origin feature_1729 ] ~/projects/<appname>
Workflow Step 2: Create a new branch for your work Name your branch with your issue number, say #1729. Branch off from devel: $ git checkout -b feature_1729 devel In the command above, feature 1729 is the name of the branch being created. Please don t use the word feature when naming your branch!
Workflow Step 2: Create a new branch for your work GitLab (hpcgitlab.inl.gov) upstream master devel devel review, test, merge Idaholab/<appname> git fetch upstream 1 git checkout devel [ git rebase upstream/devel ] 3 git add [ git commit ] origin 5 Pull Request feature_1729 2 [ git checkout b feature_1729 devel ] username/<appname> feature_1729 4 [ git push origin feature_1729 ] ~/projects/<appname>
Workflow Step 3: Add, modify, and commit code to address the issue This step is obviously specific to the problem at hand, but you will frequently use the commands: 1 git add Add untracked files. 2 git status Print a summary of what s changed. 3 git checkout Revert changes to particular files. 4 git diff Print a detailed view of your changes. When you are done, commit your changes locally: $ git commit -a -m"some message which mentions #1729."
Workflow Step 3: Add, modify, and commit code to address the issue GitLab (hpcgitlab.inl.gov) upstream master devel devel review, test, merge Idaholab/<appname> git fetch upstream 1 git checkout devel [ git rebase upstream/devel ] 3 git add [ git commit ] origin 5 Pull Request feature_1729 2 [ git checkout b feature_1729 devel ] username/<appname> feature_1729 4 [ git push origin feature_1729 ] ~/projects/<appname>
Workflow Step 4: Push your work up to your fork When you are ready to share your work with others, first make sure you are up to date: $ git fetch upstream $ git rebase upstream/devel Make sure the code still compiles and the tests run. Then push the branch to your fork, which by default is called origin : $ git push origin feature_1729 You (and others!) should now be able to see this new branch, and browse the commits directly on the GitLab site. You can also easily share work between different computers you own using GitLab.
Workflow Step 4: Push your work up to your fork GitLab (hpcgitlab.inl.gov) upstream master devel devel review, test, merge Idaholab/<appname> git fetch upstream 1 git checkout devel [ git rebase upstream/devel ] 3 git add [ git commit ] origin 5 Pull Request feature_1729 2 [ git checkout b feature_1729 devel ] username/<appname> feature_1729 4 [ git push origin feature_1729 ] ~/projects/<appname>
Workflow Step 4: Push your work up to your fork The Network shows your commits in relation to others.
Workflow Step 5: Create a Merge Request on GitLab Once your branch is ready to be merged, you can alert other developers by creating a Merge Request.
Workflow Step 5: Create a Merge Request on GitLab Your merge request should be made on your project s devel branch (not master).
Workflow Step 5: Create a Merge Request on GitLab GitLab (hpcgitlab.inl.gov) upstream master devel devel review, test, merge Idaholab/<appname> git fetch upstream 1 git checkout devel [ git rebase upstream/devel ] 3 git add [ git commit ] origin 5 Pull Request feature_1729 2 [ git checkout b feature_1729 devel ] username/<appname> feature_1729 4 [ git push origin feature_1729 ] ~/projects/<appname>
Workflow Step 6: Monitor and respond to comments on your merge request Your merge request will be automatically updated when: 1 The continuous integration system, moosebuild, tests your new code. 2 The application developers make comments. 3 Your code is merged, or your merge request is closed for any reason. Important: pushing new commits to the Merge Request branch does not trigger moosebuild to re-test your code (we will support this soon). As a workaround, simply edit the Merge Request description to trigger moosebuild to re-test.
Workflow Step 6: Monitor and respond to comments on your merge request If you change a commit that has already been pushed to your fork, it s called rewriting history. Let s say you want to edit only the most recently pushed commit. First make all the necessary changes, including adding new files, and then run $ git commit -a --amend You will also be able to edit the most recent commit message. This is a good way to add a forgotten issue number! Push the change up to your fork using the -f flag: $ git push -f origin feature_1729
Workflow Summary 0 Create/decide issue to work on, say #1729. 1 Pull down the latest changes from upstream. 2 Create a branch named feature 1729. 3 Modify code, create new files, etc. to fix the issue. 4 Push your work up to your fork. 5 Create a merge request from your fork into idaholab:devel. 6 Monitor and respond to comments on your merge request.