[MITgcm-devel] migration to github and readthedocs

Wed Jul 19 09:34:51 EDT 2017

Thanks Ryan. 

Good point about `rebase` Vs `pull`. I didn’t recommend `rebase` in the documentation because it’s harder to make a complete mess with `merge`, and I quite like being able to see when/if the master branch was merged into feature branches. Given the large code base and the likelihood of most code changes being orthogonal, I decided that we were unlikely to have the history polluted with numerous merge commits. I’m happy either way, I just was trying to make the workflow harder to mess up for people unfamiliar with git.

> (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.)

It’s possible to create situations where this step is important - for example two people working on the same repository that is a fork of an upstream repo. But, yes, for the sort of workflow we’re suggesting (individual people creating their own forks), it is unlikely to be necessary.

Ed

> On 19 Jul 2017, at 09:03, Ryan Abernathey <ryan.abernathey at gmail.com> wrote:
> 
> 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 <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/ <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 <https://github.com/altMITgcm/MITgcm66h/pull/7>
> 
> Cheers,
> Ryan
> 
> 
> 
> 
> On Wed, Jul 19, 2017 at 8:20 AM, Edward Doddridge <edoddridge at gmail.com <mailto: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 <mailto: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 <mailto: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 <mailto: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 <mailto: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 <mailto: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 <mailto: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/ <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 <mailto: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 <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 <mailto: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 <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 <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 <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 <http://github.com/>
> >>>>>>>> (https://github.com <https://github.com/>), travis.org <http://travis.org/> (https://travis-ci.org <https://travis-ci.org/>) (which
> >>>>>>>> automates some testreport checking - see
> >>>>>>>> http://altmitgcm66h.readthedocs.io/en/latest/contributing.html#automatic-testing-with-travis-ci <http://altmitgcm66h.readthedocs.io/en/latest/contributing.html#automatic-testing-with-travis-ci>
> >>>>>>>> and https://github.com/altMITgcm/MITgcm66h/blob/master/.travis.yml <https://github.com/altMITgcm/MITgcm66h/blob/master/.travis.yml>)
> >>>>>>>> and readthedocs.io <http://readthedocs.io/> (https://readthedocs.org <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 <http://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 <mailto:MITgcm-devel at mitgcm.org>
> >>>>>>>> http://mitgcm.org/mailman/listinfo/mitgcm-devel <http://mitgcm.org/mailman/listinfo/mitgcm-devel>
> >>>>>>>
> >>>>>>>
> >>>>>>> _______________________________________________
> >>>>>>> MITgcm-devel mailing list
> >>>>>>> MITgcm-devel at mitgcm.org <mailto:MITgcm-devel at mitgcm.org>
> >>>>>>> http://mitgcm.org/mailman/listinfo/mitgcm-devel <http://mitgcm.org/mailman/listinfo/mitgcm-devel>
> >>>>>>
> >>>>>>
> >>>>>> _______________________________________________
> >>>>>> MITgcm-devel mailing list
> >>>>>> MITgcm-devel at mitgcm.org <mailto:MITgcm-devel at mitgcm.org>
> >>>>>> http://mitgcm.org/mailman/listinfo/mitgcm-devel <http://mitgcm.org/mailman/listinfo/mitgcm-devel>
> >>>>>
> >>>>> _______________________________________________
> >>>>> MITgcm-devel mailing list
> >>>>> MITgcm-devel at mitgcm.org <mailto:MITgcm-devel at mitgcm.org>
> >>>>> http://mitgcm.org/mailman/listinfo/mitgcm-devel <http://mitgcm.org/mailman/listinfo/mitgcm-devel>
> >>>>
> >>>>
> >>>> _______________________________________________
> >>>> MITgcm-devel mailing list
> >>>> MITgcm-devel at mitgcm.org <mailto:MITgcm-devel at mitgcm.org>
> >>>> http://mitgcm.org/mailman/listinfo/mitgcm-devel <http://mitgcm.org/mailman/listinfo/mitgcm-devel>
> >>>
> >>>
> >>> _______________________________________________
> >>> MITgcm-devel mailing list
> >>> MITgcm-devel at mitgcm.org <mailto:MITgcm-devel at mitgcm.org>
> >>> http://mitgcm.org/mailman/listinfo/mitgcm-devel <http://mitgcm.org/mailman/listinfo/mitgcm-devel>
> >>
> >>
> >> _______________________________________________
> >> MITgcm-devel mailing list
> >> MITgcm-devel at mitgcm.org <mailto:MITgcm-devel at mitgcm.org>
> >> http://mitgcm.org/mailman/listinfo/mitgcm-devel <http://mitgcm.org/mailman/listinfo/mitgcm-devel>
> >
> >
> > _______________________________________________
> > MITgcm-devel mailing list
> > MITgcm-devel at mitgcm.org <mailto:MITgcm-devel at mitgcm.org>
> > http://mitgcm.org/mailman/listinfo/mitgcm-devel <http://mitgcm.org/mailman/listinfo/mitgcm-devel>
> 
> 
> _______________________________________________
> MITgcm-devel mailing list
> MITgcm-devel at mitgcm.org <mailto:MITgcm-devel at mitgcm.org>
> http://mitgcm.org/mailman/listinfo/mitgcm-devel <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/69db1938/attachment-0001.htm>