diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 150bcd1a..5cedaa47 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -6,17 +6,14 @@ The Developer Workflow General Notes ============= -* The terminology we use is based on the `Integrator Workflow - `_ +* We expect contributors to use a forking workflow `as described here + `_. -* Use a branching workflow similar to the one described at - http://progit.org/book/ch3-4.html. +* Keep your own "main" branch in sync with the mainline + repository's "main" branch. Specifically, do not push your + own commits directly to your "main" branch. -* Keep your own "master" branch in sync with the mainline - repository's "master" branch. Specifically, do not push your - own commits directly to your "master" branch. - -* Any commit should *pass all tests* (see `Running Tests`_). +* Any pull request should *pass all tests* (see `Running Tests`_). * See the `An Example`_ section below for a full walk through @@ -29,12 +26,15 @@ General Notes Issuing a Pull Request ====================== +* Please make sure you describe the changes you made to the code in the + `CHANGELOG `_. + * When you are ready to move changes from one of your topic branches into the - "master" branch, it must be reviewed and accepted by another developer. + "main" 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 master branch. + pull request to the main branch. Reviewing a Pull Request ======================== @@ -51,7 +51,7 @@ Reviewing a Pull Request * 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 "master" branch. + from the current HEAD of the mainline "main" branch Running Tests ============= @@ -59,15 +59,15 @@ Running Tests You can run the tests yourself using: - for Cyclus: - .. code-block:: bash + .. code-block:: console $ cyclus_unit_tests - - for Cycamore: + - for Recycle: - .. code-block:: bash + .. code-block:: console - $ recyle_unit_tests + $ recycle_unit_tests Cautions ======== @@ -75,7 +75,7 @@ Cautions * **DO NOT** rebase any commits that have been pulled/pushed anywhere else other than your own fork (especially if those commits have been integrated into the blessed repository). You should NEVER rebase commits that are a part of the - 'master' branch. *If you do, we will never, ever accept your pull request*. + 'main' branch. *If you do, we will never, ever accept your pull request*. An Example ========== @@ -83,98 +83,114 @@ 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. +As this type of workflow can be complicated, 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 Cyclus and Workflow ------------------------------ +call this branch ``work``. So, when all is said and done, in our fork there will be +two branches: ``main`` and ``work`` -We begin with a fork of the main ("blessed") Cyclus repository. After initially forking -the repo, we will have two branches in our fork: "Master" and "Develop". +We begin with a fork of the mainline Recycle repository. After initially forking +the repo, we will have the ``main`` branch in your fork. -Acquiring a Fork of the Cyclus Repository +Acquiring a Fork of the Recycle Repository ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -A fork is *your* copy of Cyclus. 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 ``cyclus/core``. Note that git -refers to your fork as "origin". +A fork is *your* copy of Recycle. Github offers an excellent `tutorial +`_ +on how to create a fork and then setup your local development evnironment with +remote connections to both the ``upstream`` repository at ``cyclus/recycle`` and +your fork of this repository referred to as ``origin``. -First, let's make our "work" branch: +First, let's make our ``work`` branch. Assuming that you are in the ``recycle`` directory: :: - .../cyclus_dir/$ git branch work - .../cyclus_dir/$ git push origin work + $ git branch work + $ git checkout work + $ git push origin work -We now have the following situation: there exists the "blessed" 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. +We now have the following situation: there exists the mainline copy of the ``main`` +branch, there exists your fork's copy of the ``main`` and ``work`` branches, +*AND* there exists your *local* copy of the ``main`` and ``work`` branches. -Workflow: The Beginning -^^^^^^^^^^^^^^^^^^^^^^^ +Workflow +^^^^^^^^ 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*. :: - - .../cyclus_dir/$ git checkout master - .../cyclus_dir/$ git pull upstream master - .../cyclus_dir/$ git push origin master - - .../cyclus_dir/$ git checkout work - .../cyclus_dir/$ git pull origin work - .../cyclus_dir/$ git rebase master - .../cyclus_dir/$ git push origin work - -Perhaps a little explanation is required. We first want to make sure that this new local copy of -the master 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: - -#. we don't need to worry about the *upstream* repo because it doesn't have a work branch, and -#. we want to incorporate any changes which may have been introduced in the master 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 -http://nvie.com/posts/a-successful-git-branching-model/ +workflow, but we assume that you wish to handle conflicts as soon as possible +(so as to keep their total number small). + +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. + +Over this time, it is possible that the ``main`` branch into which you are +proposing your pull request has advanced with other changes. In order to make +sure your ``work`` branch remains up to date, you will want to periodically +rebase your ``work`` branch onto the ``upstream/main`` branch. This +process will reapply all of the changes you have made on top of the most +up-to-date version of the ``upstream/main`` branch. Even if you have not been +doing this regularly, you'll want to do it before you initiate a pull request. +:: + + $ git checkout main + $ git pull upstream main + $ git push origin main + $ git checkout work + $ git rebase main + $ git push origin work + +Note: you may need to force the push of the rebased ``work`` branch to your fork +(i.e., `git push -f origin work`). + +Once you've performed the final commit to your ``work`` branch it's +time to make a pull request online and wait for our main 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 +`_, reach out on `slack +`_ for further advice, and make changes to +your ``work`` 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. + +Synchronizing across multiple computers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +You may wish to work on different computers over time, sometime on your laptop +and other times on a desktop at 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. + +Let us imagine that you have been at the office, finished, and successfully +pushed your changes to your ``origin`` repository. You are now at home and want +to continue working a bit on your laptop. To begin, let's update our *laptop's +local branches* +:: + $ git checkout work + $ git pull origin work + +This may also be a good time to ensure your ``work`` branch is up-to-date with the +``upstream/main`` branch +:: + + $ git chekout main + $ git pull upstream main + $ git push origin main + $ git checkout work + $ git rebase main + $ git push origin work + Releases ======== If you are going through a release of Cyclus and Cycamore, check out the release procedure notes `here -`_ and +`_ and on the `website `_. diff --git a/DEPENDENCIES.rst b/DEPENDENCIES.rst index 229fab5e..79c0d15d 100644 --- a/DEPENDENCIES.rst +++ b/DEPENDENCIES.rst @@ -1,11 +1,11 @@ ############################################## -Installing Cycamore Dependencies from Binaries +Installing Recycle Dependencies from Binaries ############################################## To see user and developer documentation for this code, please visit the `Cyclus Homepage`_. -This method describes two methods for installing Cycamore's only dependency, +This method describes two methods for installing Recycle's only dependency, the Cyclus Core, from binary distributions. If you would like to install it from source code, please see the `Cyclus Core repository `_. @@ -20,7 +20,7 @@ Dependencies ==================== ================== Package Minimum Version ==================== ================== -`Cyclus` 1.4 +`Cyclus` 1.6 ==================== ================== @@ -38,13 +38,13 @@ The Cyclus Core supports two binary installation options: **Conda** is a cross-platform, user-space package manager aimed at simplifying the installation of open source software. The Cyclus project uses Conda to -distribute pre-built Cyclus and Cycamore binaries. +distribute pre-built Cyclus binaries. The **Debian package manager** simplifies the installation of open-source software. It contains all of the files required to use specific software, as well as variety of relevant information: maintainer, description, version, dependencies (other software or libraries required to use it). The Cyclus -team provides pre-built Cyclus and Cycamore Debian packages to simplify +team provides pre-built Cyclus Debian package to simplify installation for the user. These packages are available for LTS Ubuntu version 14.04 and 16.04 (though they may also work on other Linux systems). diff --git a/INSTALL.rst b/INSTALL.rst index dc1cfdb2..36059140 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -17,7 +17,7 @@ Recycle's only dependency is the Cyclus Core. ==================== ================== Package Minimum Version ==================== ================== -`Cyclus` 1.4 +`Cyclus` 1.6 ==================== ================== There are a number of ways to install the Cyclus core: diff --git a/README.rst b/README.rst index d1f03091..a7ce76c4 100644 --- a/README.rst +++ b/README.rst @@ -1,25 +1,21 @@ ################################################### -Cycamore : The CYClus Additional MOdules REpository +Recycle ################################################### -Additional modules for the Cyclus nuclear fuel cycle simulator from the +Additional archetypes for the Cyclus nuclear fuel cycle simulator from the University of Wisconsin - Madison are intended to support innovative -fuel cycle simulations with the Cyclus fuel cycle simulator. +fuel cycle simulations with Cyclus. The archetypes in this library are +more advanced than those present in the `Cycamore Library `_. This README is intended primarily for those who intend to contribute to the -development of Cycamore archetypes. If you are interested in Cyclus as a user -or in developing your own Cyclus archetyes, you may want to consult `Getting +development of Recycle archetypes. If you are interested in Cyclus as a user +or in developing your own Cyclus archetypes, you may want to consult `Getting Started with Cyclus `_. This README provides basic information about: - - the dependency required by Cycamore - - installation of Cycamore from the command line - - how to run Cycamore unit tests - -Although Cycamore is meant to enable a basic fuel cycle simulation, you may want -more functionality than it offers. Third party modules can also be installed -(or developed) with additional facilities. Please visit the Cyclus website for -a list of `contributed modules `_. + - the dependency required by Recycle + - installation of Recycle from the command line + - how to run Recycle unit tests - **For general information about Cyclus, visit the** `Cyclus Homepage`_, @@ -29,7 +25,7 @@ a list of `contributed modules `_, -- **If you would like to contribute to Cycamore, please check our** +- **If you would like to contribute to Recycle, please check our** `Contribution Guidelines `_. @@ -40,12 +36,12 @@ a list of `contributed modules `_ ****************************** -Quick Cycamore Installation +Quick Recycle Installation ****************************** -Assuming you have the dependencies installed correctly, installing Cyclus using +Assuming you have the dependencies installed correctly, installing Recycle using github is fairly straightforward: -- Clone the Cyclus Repo: ``git clone https://github.com/cyclus/recyle.git``, - -- to install Cyclus locally (in ``~/.local/``) just run: ``python install.py`` - from recyle folder, +- clone the Recycle Repo: ``git clone https://github.com/cyclus/recyle.git``, -- finally, add the following Cyclus installation path (``~/.local/cyclus``) to - the **bottom** on your ``$PATH``. +- to install Recycle locally (in ``~/.local/``) just run: ``python install.py`` + from recycle folder, For more detailed installation procedure, and/or custom installation please refer to the `INSTALLATION guide `_. @@ -79,7 +72,7 @@ refer to the `INSTALLATION guide `_. Running Tests ****************************** -Installing Cycamore will also install a test driver (i.e., an executable of all of +Installing Recycle will also install a test driver (i.e., an executable of all of our tests). You can run the tests yourself via: .. code-block:: bash @@ -93,13 +86,13 @@ Contributing We happily welcome new developers into the Cyclus Developer Team. If you are willing to contribute into Cyclus, please follow this procedure: -#. Fork Cycamore repository, +#. Fork Recycle repository, #. Create a working branch on you fork from the ``master`` branch, -#. Implement your modification of the Cycamore source code, +#. Implement your modification of the Recycle source code, -#. Submit a Pull request into ``recyle/master`` branch, +#. Submit a Pull request into ``recycle/master`` branch, #. Wait for reviews/merge (the Puller cannot be the Merger).