[MITgcm-devel] migration to github and readthedocs

[Jean-Michel Campin]

Hi All,

  We have been doing some preparatory work to migrate the MITgcm code
to a git repository at github. A test/preview setup for this is at
https://github.com/altmitgcm/MITgcm66h. If you have a chance to take a
look it would be great to get any feedback at this stage. Some things
to note

o The github setup is a preview.

o Pending feedback, we are currently on track to switch to using
https://github.com/mitgcm/mitgcm_core as the  master repository for
distribution and development.

o The switch is expected to happen in September, if everything go well.

o When this switch happens the CVS repository for core code and
documentation will be frozen.

o History and change information will be carried over to github.

o The MITgcm_contrib CVS repository will remain active now, although
several things in MITgcm_contrib have already "self-migrated" to git.

There are some changes that will go with the switch to git around how
to work with MITgcm code. For development there is a primer here
http://altmitgcm66h.readthedocs.io/en/latest/contributing.html#quickstart-guide
that describes how development workflows will usually function. The
full development workflow entails user accounts set up with github.com
(https://github.com), travis.org (https://travis-ci.org) (which
automates some testreport checking - see
http://altmitgcm66h.readthedocs.io/en/latest/contributing.html#automatic-testing-with-travis-ci
and https://github.com/altMITgcm/MITgcm66h/blob/master/.travis.yml)
and readthedocs.io (https://readthedocs.org). The short form of the
workflow, in github speak, is
o fork the official repo
o clone the fork
o update code
o push to clone and test through travis
o submit pull request
o thing gets merged, assuming they pass inspection by testreport and a
master repository committer (a human!). Chris, Oliver and Jean-Michel
are the committers at present. This will evolve as we learn what we
are doing!

The other noticeable change is around the MITgcm manual which we are
planning to migrate to a format compatible with readthedocs.org. This
format can produce online and hard copy documentation. It also
integrates with development tools in github, making it easier to see
updates from edits in "realtime". The new documentation format
(restructured text or .rst) should be recognizable to anyone who
speaks latex and much latex content carries over. However, syntax for
section headings, labels, citations etc... is slightly different.
Actual equation writing syntax is generally almost the same as latex.
Ed Doddridge plus Jeff Scott have been doing a fantastic job providing
examples of changed manual sections. These show how the syntax differs
and what end product looks like.

For this mail that is probably enough. As stated earlier it would be
great to get feedback! We are planning to hold a regular WebEx call
starting in September, as another way to gather input on this and
other planned activities.

Cheers,

Chris and Jean-Michel