[MITgcm-devel] migration to github and readthedocs

Wed Jul 19 09:03:40 EDT 2017

This is a fantastic development! Big thanks to Jean Michel, Chris, Oliver,
Ed, and everyone else involved in this migration process.

I have one minor recommendation for slight change to the workflow: rather
than using "git pull upstream master" to update a local fork with the
latest master, I recommend instead "git fetch upstream; git rebase
upstream/master".

Git pull uses merge. Rebase, on the other hand, creates a cleaner commit
history. While both achieve the same end state, the history of commits is
preserved better using rebase. This difference is described in detail here
https://www.atlassian.com/git/tutorials/merging-vs-rebasing
Some of the pros and cons are discussed here:
https://blog.sourcetreeapp.com/2012/08/21/merge-or-rebase/

Most big open source projects on git today use rebase rather than merge.

(Also, I don't think the `git push origin master` step is ever necessary;
all it does it update the fork's master branch on github, which is not
actually ever used for anything.)

I just opened a new pull request with these changes to the contributing
guide:
https://github.com/altMITgcm/MITgcm66h/pull/7

Cheers,
Ryan

On Wed, Jul 19, 2017 at 8:20 AM, Edward Doddridge <edoddridge at gmail.com>
wrote:

> Great!
>
> Yes, this is all play, and the history (commit messages &c.) of this test
> repository won’t survive.
>
> However, the translated documentation in this repository will become the
> real documentation when the transition occurs, so time spent improving it
> is not wasted.
>
> (Sadly though, since the history won’t be preserved, your contributions
> won’t show up separately in the log of the real repository - whoever adds
> the files to real repository during the transition will show up as the
> author)
>
> Ed
>
>
> > On 19 Jul 2017, at 08:12, Martin Losch <Martin.Losch at awi.de> wrote:
> >
> > OK thanks,
> > I’ll give it another go with a new change to the documentation.
> >
> > This is all play, isn’t it? And I’m just testing …
> >
> > Martin
> >
> >> On 19. Jul 2017, at 14:01, Edward Doddridge <edoddridge at gmail.com>
> wrote:
> >>
> >> No worries Martin. I just commented on the pull request about using
> descriptive branch names. Thanks for diving in!
> >>
> >> Yes, this does require going through your local copy. I’m not aware of
> a way to make GitHub automatically synchronise a repository with its
> `upstream`.
> >>
> >> Ed
> >>
> >>
> >>> On 19 Jul 2017, at 07:52, Martin Losch <Martin.Losch at awi.de> wrote:
> >>>
> >>> … and I have to appologize for not following the quick start guide in
> creating branches before committing and creating pull requests,
> >>> bear with me … I am not longer under 35,
> >>>
> >>> Martin
> >>>
> >>>> On 19. Jul 2017, at 13:45, Martin Losch <Martin.Losch at awi.de> wrote:
> >>>>
> >>>> Hi Ed,
> >>>>
> >>>> thanks and I apologize for not recognizing the description in the
> quick start guide. This is what I have also found on the web, but it always
> means going through the local copy (clone) of the fork on my hard disk,
> doesn’t it? I would have thought that there should be a way of “repeating”
> the horizontal arrow from the “upstream” master to the the “origin” master
> (my fork). That does not seem possible with github, does it?
> >>>>
> >>>> Martin
> >>>>
> >>>>> On 19. Jul 2017, at 13:36, Edward Doddridge <edoddridge at gmail.com>
> wrote:
> >>>>>
> >>>>> Hi Martin,
> >>>>>
> >>>>> Making sure that your version of the repository is up to date is
> what step 2 in the quick start guide achieves.
> >>>>>
> >>>>> The commands are:
> >>>>>
> >>>>> git checkout master - which makes sure you are on the local master
> branch
> >>>>>
> >>>>> git pull upstream master && git push origin master - pull down the
> latest version of the master branch from the “upstream” repository (which
> is what we called the main repository in step 1), and then push any updates
> to the master branch of your version of the repository on GitHub (your
> version on GitHub is called “origin”)
> >>>>>
> >>>>> Once you’ve executed these commands the master branch of your local
> copy will have all the commits from the master branch of the main
> repository (“upstream”) and you will also have sent those commits to your
> copy on GitHub (“origin”).
> >>>>>
> >>>>> The git pull upstream master command would be a diagonal arrow in
> this figure, going from “upstream” to your local copy. I’ll add an arrow
> and text showing the command to the figure.
> >>>>>
> >>>>> Cheers,
> >>>>> Ed
> >>>>>
> >>>>>
> >>>>>> On 19 Jul 2017, at 06:38, Martin Losch <Martin.Losch at awi.de> wrote:
> >>>>>>
> >>>>>> It a feature in gitlab:
> >>>>>> <https://about.gitlab.com/2016/12/01/how-to-keep-your-
> fork-up-to-date-with-its-origin/>
> >>>>>>
> >>>>>> M.
> >>>>>>> On 19. Jul 2017, at 12:17, Martin Losch <Martin.Losch at awi.de>
> wrote:
> >>>>>>>
> >>>>>>> Hi Chris and Jean-Michel,
> >>>>>>>
> >>>>>>> exciting stuff, ideal for procrastination. I tried to fix
> something in the documentation for testing and this works great.
> >>>>>>> I have question (couldn't find anything useful in google, so far):
> Once I created a fork and the master (from which I forked off) evolves, how
> do I update the fork (within github)? The only explanations I found was how
> I update my local clone of my fork, and something that seems to be strange
> and complicated <https://stackoverflow.com/questions/7244321/how-do-i-
> update-a-github-forked-repository/23853061#23853061>
> >>>>>>>
> >>>>>>> I don’t know enough about this (not under 35), but shouldn’t there
> be a transparent way of keep my fork up to date with the master?
> >>>>>>>
> >>>>>>> Martin
> >>>>>>>
> >>>>>>>> On 18. Jul 2017, at 19:54, Jean-Michel Campin <jmc at mit.edu>
> wrote:
> >>>>>>>>
> >>>>>>>> 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
> >>>>>>>>
> >>>>>>>> _______________________________________________
> >>>>>>>> MITgcm-devel mailing list
> >>>>>>>> MITgcm-devel at mitgcm.org
> >>>>>>>> http://mitgcm.org/mailman/listinfo/mitgcm-devel
> >>>>>>>
> >>>>>>>
> >>>>>>> _______________________________________________
> >>>>>>> MITgcm-devel mailing list
> >>>>>>> MITgcm-devel at mitgcm.org
> >>>>>>> http://mitgcm.org/mailman/listinfo/mitgcm-devel
> >>>>>>
> >>>>>>
> >>>>>> _______________________________________________
> >>>>>> MITgcm-devel mailing list
> >>>>>> MITgcm-devel at mitgcm.org
> >>>>>> http://mitgcm.org/mailman/listinfo/mitgcm-devel
> >>>>>
> >>>>> _______________________________________________
> >>>>> MITgcm-devel mailing list
> >>>>> MITgcm-devel at mitgcm.org
> >>>>> http://mitgcm.org/mailman/listinfo/mitgcm-devel
> >>>>
> >>>>
> >>>> _______________________________________________
> >>>> MITgcm-devel mailing list
> >>>> MITgcm-devel at mitgcm.org
> >>>> http://mitgcm.org/mailman/listinfo/mitgcm-devel
> >>>
> >>>
> >>> _______________________________________________
> >>> MITgcm-devel mailing list
> >>> MITgcm-devel at mitgcm.org
> >>> http://mitgcm.org/mailman/listinfo/mitgcm-devel
> >>
> >>
> >> _______________________________________________
> >> MITgcm-devel mailing list
> >> MITgcm-devel at mitgcm.org
> >> http://mitgcm.org/mailman/listinfo/mitgcm-devel
> >
> >
> > _______________________________________________
> > MITgcm-devel mailing list
> > MITgcm-devel at mitgcm.org
> > http://mitgcm.org/mailman/listinfo/mitgcm-devel
>
>
> _______________________________________________
> MITgcm-devel mailing list
> MITgcm-devel at mitgcm.org
> http://mitgcm.org/mailman/listinfo/mitgcm-devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mitgcm.org/pipermail/mitgcm-devel/attachments/20170719/a92420b5/attachment-0001.htm>