Skip to content

Update documentation #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
abachma2 wants to merge 7 commits into
base: master
Choose a base branch
from
Open

Update documentation #22

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7a9c751
update README to Recycle from Cycamore
abachma2 Jul 15, 2025
bf20057
change instanses of cycamore to recycle
abachma2 Jul 16, 2025
f50e55f
Update CONTRIBUTING.rst with @gonuke
abachma2 Jul 16, 2025
507243b
change recycle_dir to recycle and talk about cloning
abachma2 Jul 17, 2025
45467e5
remove directory name from commands
abachma2 Jul 25, 2025
edd554a
copy from cyclus repo
abachma2 Aug 8, 2025
2ff1c92
change cyclus from recycle
abachma2 Aug 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
198 changes: 107 additions & 91 deletions CONTRIBUTING.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,14 @@ The Developer Workflow
General Notes
=============

* The terminology we use is based on the `Integrator Workflow
<http://en.wikipedia.org/wiki/Integrator_workflow>`_
* We expect contributors to use a forking workflow `as described here
<https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow>`_.

* 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

Expand All @@ -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 <CHANGELOG.rst>`_.

* 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
<https://help.github.com/articles/using-pull-requests/>`_ before you make a
pull request to the master branch.
pull request to the main branch.

Reviewing a Pull Request
========================
Expand All @@ -51,130 +51,146 @@ 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
=============

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
========

* **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
Copy link

@dean-krueger dean-krueger Aug 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've seen in other parts that the term "blessed repository" is being replaced with "mainline main" or something similar. Just in case that was intentional, wanted to point out that it was used here.

Copy link
Member Author

@abachma2 abachma2 Aug 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is probably a good thing to edit, to make sure it's consistent with the fit hub links we provide.

'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
==========

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 <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 ``cyclus/core``. Note that git
refers to your fork as "origin".
A fork is *your* copy of Recycle. Github offers an excellent `tutorial
<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo>`_
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
<http://cyclus.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 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
<http://cyclus.github.com/devdoc/style_guide.html>`_, reach out on `slack
<https://cyclus-nuclear.slack.com>`_ 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
Copy link

@dean-krueger dean-krueger Aug 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I maybe missed it, but since this tutorial is seemingly geared towards people who are unfamiliar with Git, should there also be a step where you tell people to set their upstream to the correct place? I think this is the first time I've seen upstream here. Maybe it does it automatically somehow and I didn't know that?

Copy link
Member Author

@abachma2 abachma2 Aug 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is a good idea.

$ 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
<https://github.com/cyclus/cyclus/blob/master/doc/release_procedure.rst>`_ and
<https://github.com/cyclus/cyclus/blob/main/doc/release_procedure.rst>`_ and
on the `website <http://fuelcycle.org/cep/cep3.html>`_.
10 changes: 5 additions & 5 deletions DEPENDENCIES.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
<http://github.com/cyclus/cyclus>`_.
Expand All @@ -20,7 +20,7 @@ Dependencies
==================== ==================
Package Minimum Version
==================== ==================
`Cyclus` 1.4
`Cyclus` 1.6
==================== ==================


Expand All @@ -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).

Expand Down
2 changes: 1 addition & 1 deletion INSTALL.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Loading