From 221e04135a507bedae77573be5fcc88cadcdb754 Mon Sep 17 00:00:00 2001 From: Katy Huff Date: Wed, 31 May 2017 16:53:53 -0500 Subject: [PATCH 1/6] adds contributing file. --- CONTRIBUTING.md | 184 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 184 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..2e75d4384d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,184 @@ +- [General Notes](#general-notes) +- [Issuing a Pull Request](#issuing-a-pull-request) +- [Reviewing a Pull Request](#reviewing-a-pull-request) +- [Running Tests](#running-tests) +- [Cautions](#cautions) +- [An Example](#an-example) + - [Introduction](#introduction) + - [Acquiring Moltres and Workflow](#acquiring-moltres-and-workflow) + - [See also](#see-also) +- [Releases](#releases) + +------------------------------------------------------------------------ + +# The developer Workflow + +## General Notes + +- The terminology we use is based on the + `Integrator Workflow `\_ + +- Use a branching workflow similar to the one described + at http://progit.org/book/ch3-4.html. + +- Keep your own "master" and "develop" branches in sync with the + main repository's "master" and "develop" branches. Specifically, + do not push your own commits directly to your "master" and + "develop" branches. + +- Any commit should *pass all tests* (see `Running Tests`\_). + +- See the `An Example`\_ section below for a full walk through + +- In addition to a review of the algorithmic and logical changes in + your contribution, it will be reviewed on a variety of levels + including such things as style, documentation, tests, etc. While + such review can appear tedious, these aspects are important for the + long term success of the project. + +## Issuing a Pull Request + +- When you are ready to move changes from one of your topic branches + into the "develop" branch, it must be reviewed and accepted by + another developer. + +- You may want to review this + `tutorial `\_ + before you make a pull request to the develop branch. + +## Reviewing a Pull Request + +- Look over the code. + +- Check that it meets the `MOOSE style guidelines `\_. + +- Make inline review comments concerning improvements. + +- Wait for the Continuous Integration service to show full test + passage. + +- Click the green "Merge Pull Request" button. + +- Note: if the button is not available, the requester needs to merge + or rebase from the current HEAD of the blessed's "develop" + (or "master") branch. + +## Running Tests + +You can run the tests yourself using: - for Moltres: +To ensure that Moltres is functioning properly, run the following from the +root of the Moltres directory. + +```bash +./run_tests -j8 +``` + +## Cautions + +- **NEVER** merge the "master" branch into the "develop" branch. + Changes should only flow *to* the "master" branch *from* the + "develop" branch. + +## An Example + +### Introduction + +As this type of workflow can be complicated to converts from SVN and +very complicated for brand new programmers, an example is provided. + +For the sake of simplicity, let us assume that we want a single +"sandbox" branch in which we would like to work, i.e. where we can store +all of our work that may not yet pass tests or even compile, but where +we also want to save our progress. Let us call this branch "Work". So, +when all is said and done, in our fork there will be three branches: +"master", "develop", and "Work". + +### Acquiring Moltres and Workflow + +We begin with a fork of the main Moltres repository. After initially forking the +repo, we will have two branches in our fork: "master" and "develop". + +#### Acquiring a Fork of the Moltres Repository + +A fork is *your* copy of Moltres. Github offers an excellent +`tutorial `\_ on how to set one up. +The rest of this example assumes you have set up the "upstream" +repository as `moltres/core`. Note that git refers to your fork as +"origin". + +First, let's make our "work" branch: :: .../moltres\_dir/\$ git branch +work .../moltres\_dir/\$ git push origin work + +We now have the following situation: + +- there exists the main copy of the master and develop branches, +- there exists your fork's copy of the master, develop, and Work branches, + -*AND* there exists your *local* copy of the master, develop, and Work branches. + +It is important now to note that you may wish to work from home or the office. +If you keep your fork's branches up to date (i.e., "push" your changes before +you leave), only your *local* copies of your branches may be different when you +next sit down at the other location. + +### Workflow: The Beginning + +Now, for the workflow! This is by no means the only way to perform this +type of workflow, but I assume that you wish to handle conflicts as +often as possible (so as to keep their total number small). Let us +imagine that you have been at work, finished, and successfully pushed +your changes to your *origin* repository. You are now at home and want +to continue working a bit. To begin, let's update our *home's local +branches*. :: + +``` + .../moltres_dir/$ git checkout develop + .../moltres_dir/$ git pull upstream develop + .../moltres_dir/$ git push origin develop + + .../moltres_dir/$ git checkout work + .../moltres_dir/$ git pull origin work + .../moltres_dir/$ git rebase develop + .../moltres_dir/$ git push origin work +``` + +Perhaps a little explanation is required. We first want to make sure +that this new local copy of the develop branch is up-to-date with +respect to the remote origin's branch and remote upstream's branch. If +there was a change from the remote upstream's branch, we want to push +that to origin. We then follow the same process to update the work +branch, except: + +1. we don't need to worry about the *upstream* repo because it doesn't + have a work branch, and +2. we want to incorporate any changes which may have been introduced in + the develop branch update. + +#### Workflow: The End + +As time passes, you make some changes to files, and you commit those +changes (to your *local work branch*). Eventually (hopefully) you come +to a stopping point where you have finished your project on your work +branch *AND* it compiles *AND* it runs input files correctly *AND* it +passes all tests! Perhaps you have found Nirvana. In any case, you've +performed the final commit to your work branch, so it's time to make a +pull request online and wait for our developer friends to review and +accept it. + +Sometimes, your pull request will be held by the reviewer until further +changes are made to appease the reviewer's concerns. This may be +frustrating, but please act rationally, discuss the issues on the GitHub +space made for your pull request, consult the +`style guide `\_, +email the developer listhost for further advice, and make changes to +your topic branch accordingly. The pull request will be updated with +those changes when you push them to your fork. When you think your +request is ready for another review, you can reopen the review yourself +with the button made available to you. + +#### See also + +A good description of a git workflow with good graphics is available at +[nvie](http://nvie.com/posts/a-successful-git-branching-model/). + +This contributor document was isnpired by the one written by the `Cyclus team +`\_. From 3679914b9c4a6e02629af2979aeff1140eb3ba84 Mon Sep 17 00:00:00 2001 From: Katy Huff Date: Wed, 31 May 2017 16:59:23 -0500 Subject: [PATCH 2/6] rst to md --- CONTRIBUTING.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2e75d4384d..0fb9133aeb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,19 +16,19 @@ ## General Notes - The terminology we use is based on the - `Integrator Workflow `\_ + [Integrator Workflow ](http://en.wikipedia.org/wiki/Integrator_workflow). - Use a branching workflow similar to the one described - at http://progit.org/book/ch3-4.html. + in the [progit gitbook](http://progit.org/book/ch3-4.html). - Keep your own "master" and "develop" branches in sync with the main repository's "master" and "develop" branches. Specifically, do not push your own commits directly to your "master" and "develop" branches. -- Any commit should *pass all tests* (see `Running Tests`\_). +- Any commit should *pass all tests* (see [Running Tests](#running-tests)). -- See the `An Example`\_ section below for a full walk through +- See the [An Example](#an-example) section below for a full walk through. - In addition to a review of the algorithmic and logical changes in your contribution, it will be reviewed on a variety of levels @@ -43,14 +43,14 @@ another developer. - You may want to review this - `tutorial `\_ + [tutorial](https://help.github.com/articles/using-pull-requests/) before you make a pull request to the develop branch. ## Reviewing a Pull Request - Look over the code. -- Check that it meets the `MOOSE style guidelines `\_. +- Check that it meets the [MOOSE style guidelines](http://mooseframework.org/wiki/CodeStandards/). - Make inline review comments concerning improvements. @@ -101,7 +101,7 @@ repo, we will have two branches in our fork: "master" and "develop". #### Acquiring a Fork of the Moltres Repository A fork is *your* copy of Moltres. Github offers an excellent -`tutorial `\_ on how to set one up. +[tutorial](http://help.github.com/fork-a-repo/) on how to set one up. The rest of this example assumes you have set up the "upstream" repository as `moltres/core`. Note that git refers to your fork as "origin". @@ -168,7 +168,7 @@ Sometimes, your pull request will be held by the reviewer until further changes are made to appease the reviewer's concerns. This may be frustrating, but please act rationally, discuss the issues on the GitHub space made for your pull request, consult the -`style guide `\_, +[style guide](http://moltres.github.com/devdoc/style_guide.html), email the developer listhost for further advice, and make changes to your topic branch accordingly. The pull request will be updated with those changes when you push them to your fork. When you think your @@ -180,5 +180,5 @@ with the button made available to you. A good description of a git workflow with good graphics is available at [nvie](http://nvie.com/posts/a-successful-git-branching-model/). -This contributor document was isnpired by the one written by the `Cyclus team -`\_. +This contributor document was isnpired by the one written by the [Cyclus team +](github.com/cyclus/cyclus). From 363f6e2473643421762f863e1b1bc394812eedfe Mon Sep 17 00:00:00 2001 From: Katy Huff Date: Wed, 31 May 2017 17:00:10 -0500 Subject: [PATCH 3/6] nvie->here --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0fb9133aeb..8837ccbfe6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,7 +11,7 @@ ------------------------------------------------------------------------ -# The developer Workflow +# The Developer Workflow ## General Notes @@ -177,8 +177,8 @@ with the button made available to you. #### See also -A good description of a git workflow with good graphics is available at -[nvie](http://nvie.com/posts/a-successful-git-branching-model/). +A good description of a git workflow with good graphics is available +[here](http://nvie.com/posts/a-successful-git-branching-model/). This contributor document was isnpired by the one written by the [Cyclus team ](github.com/cyclus/cyclus). From 13cfed842719d2f77af486409cce8613bb471728 Mon Sep 17 00:00:00 2001 From: Katy Huff Date: Wed, 31 May 2017 17:00:46 -0500 Subject: [PATCH 4/6] title before toc --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8837ccbfe6..0e3af228b6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,5 @@ +# The Developer Workflow + - [General Notes](#general-notes) - [Issuing a Pull Request](#issuing-a-pull-request) - [Reviewing a Pull Request](#reviewing-a-pull-request) @@ -11,8 +13,6 @@ ------------------------------------------------------------------------ -# The Developer Workflow - ## General Notes - The terminology we use is based on the From 33cdd55c218b218e9a623785050eb1df9f0a08f6 Mon Sep 17 00:00:00 2001 From: Katy Huff Date: Wed, 31 May 2017 17:02:17 -0500 Subject: [PATCH 5/6] level headings --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0e3af228b6..e5a13b9ea8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -120,7 +120,7 @@ If you keep your fork's branches up to date (i.e., "push" your changes before you leave), only your *local* copies of your branches may be different when you next sit down at the other location. -### Workflow: The Beginning +#### Workflow: The Beginning Now, for the workflow! This is by no means the only way to perform this type of workflow, but I assume that you wish to handle conflicts as From 3851cf538709afc941ad55aa8c436b5e9aaca3b2 Mon Sep 17 00:00:00 2001 From: Katy Huff Date: Wed, 31 May 2017 17:27:30 -0500 Subject: [PATCH 6/6] search and replace develop with devel --- CONTRIBUTING.md | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e5a13b9ea8..2923daac2e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,10 +21,10 @@ - Use a branching workflow similar to the one described in the [progit gitbook](http://progit.org/book/ch3-4.html). -- Keep your own "master" and "develop" branches in sync with the - main repository's "master" and "develop" branches. Specifically, +- Keep your own "master" and "devel" branches in sync with the + main repository's "master" and "devel" branches. Specifically, do not push your own commits directly to your "master" and - "develop" branches. + "devel" branches. - Any commit should *pass all tests* (see [Running Tests](#running-tests)). @@ -39,12 +39,12 @@ ## Issuing a Pull Request - When you are ready to move changes from one of your topic branches - into the "develop" branch, it must be reviewed and accepted by - another developer. + into the "devel" branch, it must be reviewed and accepted by + another develer. - You may want to review this [tutorial](https://help.github.com/articles/using-pull-requests/) - before you make a pull request to the develop branch. + before you make a pull request to the devel branch. ## Reviewing a Pull Request @@ -60,7 +60,7 @@ - Click the green "Merge Pull Request" button. - Note: if the button is not available, the requester needs to merge - or rebase from the current HEAD of the blessed's "develop" + or rebase from the current HEAD of the blessed's "devel" (or "master") branch. ## Running Tests @@ -75,9 +75,9 @@ root of the Moltres directory. ## Cautions -- **NEVER** merge the "master" branch into the "develop" branch. +- **NEVER** merge the "master" branch into the "devel" branch. Changes should only flow *to* the "master" branch *from* the - "develop" branch. + "devel" branch. ## An Example @@ -91,12 +91,12 @@ For the sake of simplicity, let us assume that we want a single all of our work that may not yet pass tests or even compile, but where we also want to save our progress. Let us call this branch "Work". So, when all is said and done, in our fork there will be three branches: -"master", "develop", and "Work". +"master", "devel", and "Work". ### Acquiring Moltres and Workflow We begin with a fork of the main Moltres repository. After initially forking the -repo, we will have two branches in our fork: "master" and "develop". +repo, we will have two branches in our fork: "master" and "devel". #### Acquiring a Fork of the Moltres Repository @@ -111,9 +111,9 @@ work .../moltres\_dir/\$ git push origin work We now have the following situation: -- there exists the main copy of the master and develop branches, -- there exists your fork's copy of the master, develop, and Work branches, - -*AND* there exists your *local* copy of the master, develop, and Work branches. +- there exists the main copy of the master and devel branches, +- there exists your fork's copy of the master, devel, and Work branches, + -*AND* there exists your *local* copy of the master, devel, and Work branches. It is important now to note that you may wish to work from home or the office. If you keep your fork's branches up to date (i.e., "push" your changes before @@ -131,18 +131,18 @@ to continue working a bit. To begin, let's update our *home's local branches*. :: ``` - .../moltres_dir/$ git checkout develop - .../moltres_dir/$ git pull upstream develop - .../moltres_dir/$ git push origin develop + .../moltres_dir/$ git checkout devel + .../moltres_dir/$ git pull upstream devel + .../moltres_dir/$ git push origin devel .../moltres_dir/$ git checkout work .../moltres_dir/$ git pull origin work - .../moltres_dir/$ git rebase develop + .../moltres_dir/$ git rebase devel .../moltres_dir/$ git push origin work ``` Perhaps a little explanation is required. We first want to make sure -that this new local copy of the develop branch is up-to-date with +that this new local copy of the devel branch is up-to-date with respect to the remote origin's branch and remote upstream's branch. If there was a change from the remote upstream's branch, we want to push that to origin. We then follow the same process to update the work @@ -151,7 +151,7 @@ branch, except: 1. we don't need to worry about the *upstream* repo because it doesn't have a work branch, and 2. we want to incorporate any changes which may have been introduced in - the develop branch update. + the devel branch update. #### Workflow: The End @@ -161,7 +161,7 @@ to a stopping point where you have finished your project on your work branch *AND* it compiles *AND* it runs input files correctly *AND* it passes all tests! Perhaps you have found Nirvana. In any case, you've performed the final commit to your work branch, so it's time to make a -pull request online and wait for our developer friends to review and +pull request online and wait for our develer friends to review and accept it. Sometimes, your pull request will be held by the reviewer until further @@ -169,7 +169,7 @@ changes are made to appease the reviewer's concerns. This may be frustrating, but please act rationally, discuss the issues on the GitHub space made for your pull request, consult the [style guide](http://moltres.github.com/devdoc/style_guide.html), -email the developer listhost for further advice, and make changes to +email the develer listhost for further advice, and make changes to your topic branch accordingly. The pull request will be updated with those changes when you push them to your fork. When you think your request is ready for another review, you can reopen the review yourself