Get prepared for CABLE moving to git and GitHub

Land Surface CABLE
1

We are planning to move CABLE from an SVN/TRAC-based repository to a git/GitHub-based repository. We will use this forum to communicate information about the changes.

How to stay informed

The simplest way to stay informed about the move of CABLE to GitHub is to watch the cable-to-git tag (you will need to sign up for the forum first if you haven’t already). To watch the tag, go to this page and click the :bell: icon on the top right. You can then choose the level of notification that is appropriate to you. Know that “watch” is the strongest level and will email you all activities on topics with the cable-to-git tag.

If you do not want notifications, all topics on the subject will be tagged with cable-to-git so you can search for this tag on the forum to find the information.

Events

What is happening

The CABLE SVN repository and the TRAC tickets will be moved to be hosted by GitHub and to use git as a version control system. The documentation is also in the process of being rewritten and hosted by Read the Docs.
At this time, the datasets in CABLE-AUX will stay under SVN and the TRAC site and will move on at a later date.

At this stage, we estimate moving CABLE from SVN to GitHub will take a day. From that day, the access to the SVN repository will be restricted to read-only so all work on editing the CABLE code source should be paused for that day.
After the transition, all activity on CABLE will happen on GitHub, using git. The current SVN repository and Trac site will stay accessible but in read-only mode.

The SVN repository and Trac site will be definitely removed about 7 years after the transition. This time frame was chosen as some publications may have used the Trac URL to refer to specific CABLE versions and these should be accessible for 7 years.

We know this transition is a big change and we would like to ensure everyone will be able to adapt in the best conditions. In the coming weeks, there will be various information being released such as new working practices for CABLE with the git/GitHub workflow and a git/GitHub training. We also need you to take a few actions now.

What we need you to do

  1. Tell us, by replying on this forum topic, what concerns you have about the transition so we can work with you to prepare for it. In particular, we would like to know if you need time before the transition to adapt existing workflows or other preparation work, and how much time would be needed. At this time, the transition could happen as early as late November unless users need more time.

  2. We need you to tell us which branches of the CABLE repository should be carried over to GitHub, by Friday 27 October. Please go to this topic for more details and reply there with your important branches.

  3. Learn Git and GitHub. There are plenty of resources around to learn Git. Searching for “Git Tutorial” on YouTube will give you many options. You can also use:

    We will also soon release a short training targeted specifically at how we will use Git for CABLE.

1 Like
3

Dear Claire,

I use github actions and github pages with my projects. For the latter, I have the special target:

github:
	@make html
	@rsync -arv --delete build/html/ ./html/

in my Makefile in the docs/ directory.

I also have a file index.html in there with the content:

<meta http-equiv="refresh" content="0; url=./html/index.html" />

so that people get redirected to html/index.html directly.

So I only have to type:

make github

on the command line to have the documentation updated (have to commit/push it, though).

Works great and I do not have another dependency to ReadTheDocs.

Regards,
Matthias

4

Thanks Matthias. I also started with GitHub pages, but found Read the Docs was worth it for its gestion of versioning.

It also handles previews for pull requests very well and easily. With GitHub pages, we had problems with deployment speed when too many pull requests were open (>4-5).

5

Here are a few announcements about the CABLE move to GitHub.

Remember to tell us about your code branches

We will not carry over all the branches in the CABLE repository. Remember to let us know about your current branches you will need on GitHub.

Date for moving the repository

As it stands, we are planning on moving the repository on Monday 27 November. We will confirm the date closer to that time, feel free to add it to your calendars for now.

I would recommend to avoid working on CABLE on that date. Otherwise, you risk losing the changes you make to the code or at the very least, you would have to copy them over by hand.

A reminder there will not be an overlap period with both SVN and git repositories available. It is much easier for everyone to transition completely over one day, even if you still have to learn git.

Git and GitHub training

We have prepared a training around git and GitHub to help you adapt. The training video is now available on YouTube. The video is quite long but is divided into chapters to jump directly to a section of interest. The chapters are listed under the video in the description or are visible in the video’s timeline when scrolling.

We will hold a 1-hour question time on Tuesday 14 November at 10 am. You will be able to ask your questions about git, GitHub and the planned move. We are available to run additional drop-in sessions, if you are interested, please let us know the best times for you for these sessions.

Pre-requisites: The training contains a couple of exercises which have some pre-requisites. Most are explained in the video but here is a list:

Additional resources

Closer to the transition date, we will release new documentation. Although this CABLE documentation will still be incomplete, it will contain the contributor’s guidelines with some explanations around the use of git and GitHub and some cheat sheets.

On Tuesday 28 November, we are running a CABLE docathon on that day. This is a perfect time to get help getting started with CABLE on GitHub.

For long-term support, web searches and Stackoverflow are great sources of information on git and GitHub. A lot of members of this forum are experts in using these tools and would happily help you out without judgment. The CABLE admin team is also available to help, the best way to contact them is via an issue on GitHub with the mention @CABLE-LSM/admins.

7

Hello,

This is a reminder about our 1-hour question time this Tuesday, 14/11 at 10 am. You will be able to ask your questions about using git and GitHub. Please see the top post in this topic for all information about this session.

Here is the training video for git and GitHub.

8

Hi,

I was told I had forgotten the Zoom link for the Git and GitHub Q&A. Here it is: Launch Meeting - Zoom

The event was also updated with the link.

9

I use the GitHub CLI client and find it really good

It is available from the CLEX CMS conda environments and can be invoked with gh and can authenticate to GitHub and create an API token so ssh keys aren’t required when using it.

$ gh auth --help
Authenticate gh and git with GitHub

USAGE
  gh auth <command> [flags]

AVAILABLE COMMANDS
  login:       Authenticate with a GitHub host
  logout:      Log out of a GitHub host
  refresh:     Refresh stored authentication credentials
  setup-git:   Setup git with GitHub CLI
  status:      View authentication status
  token:       Print the auth token gh is configured to use

INHERITED FLAGS
  --help   Show help for command

LEARN MORE
  Use 'gh <command> <subcommand> --help' for more information about a command.
  Read the manual at https://cli.github.com/manual

It might be a lower barrier for entry for some users. Or some might just prefer it.

10

Date for moving CABLE repository to GitHub

This is to confirm the CABLE repository will move to GitHub on Monday 27 November.

Make sure you commit all your changes to CABLE by the end of Friday 24 November.

I would recommend you avoid working on CABLE development on Monday 27 November.

CABLE docathon

A CABLE docathon is scheduled for Tuesday 28 November. This is a great opportunity for anyone wanting to start or continue developing CABLE to get one-on-one help to get started with the GitHub setup.

1 Like
11

CABLE transfer to git and GitHub has started

As announced earlier, the transfer of the CABLE repository to git and GitHub has now started. Please avoid working on the CABLE svn repository today.

12

CABLE transfer to GitHub is completed

CABLE has now been successfully transferred to GitHub. The home of the CABLE code is now:

Directory structure changes

We are now hosting the source code for CABLE and its documentation together. As such, the CABLE source code is now under src/ while the documentation sits under documentation/.

Where to find your branch

The CABLE GitHub repository should have a branch for all the requested branches with the same name with the exception of:

  • Ticket339 is renamed to 171-bug-in-offline-zenith-angle-calculation
  • Ticket334 is renamed to 173-thresholds-in-albedo

These branches were renamed to correspond to their accompanying issues.

What to do to continue working with CABLE

Please refer to the CABLE documentation to get more information on how to use CABLE now. In particular, there is now a Contribution guide for anyone who wants to work on modifications to the CABLE code.

:warning: The CABLE documentation is currently a work-in-progress. Any contribution to improve CABLE’s documentation is welcome.

1 Like