Posted inInformation Technology

How to Fork a Mercurial Project on SourceForge

seasoned_geek by seasoned_geek
SourceForge logo

Forking a Mercurial project on SourceForge isn’t as straight forward as one might think. If you jump straight to fork without first creating a project, you are going to end up with a personal tool.

CSScintilla originally forked as personal tool

A personal tool is fine if you are working on a new feature you hope might one day be included in the project from whence you forked. In my case I was adding CopperSpice support to Scintilla because Qt no longer qualifies as OpenSource with the removal of an OpenSource LTS. The community isn’t allowed to create on on their own. Many projects and some Linux distros are now removing all things Qt. Debian no longer has any Qt maintainers. They are using the KDE project repos but many/most Debian based distros have long since dropped KDE as a supported desktop, instead favoring desktops with less bloat and fewer useless applications.

Scintilla didn’t want to absorb yet another cross platform library which was fine. I need CsScintilla for the next release of RedDiamond because syntax highlighting with QPlaneTextEdit and Regular Expressions just sucked on big files.

So, I went the path most will go with Mercurial.

  • Forked project to personal tool
  • Finished what you were working on and now want to make this available to others
  • You also want to maintain the ability to pull updates into your code from the original project
  • Gee, how do I do that?

The part that isn’t obvious

When you fork a Mercurial based project you have to fork it into something. Let me show you some shots.

Choosing to fork Scintilla
If you take the defaults you get a personal tool

How to go from personal tool to project

First you must create a new project. This is the counterintuitive part, but you cannot create a new project via fork with Mercurial like you can with Git and many other Source Code Management (SCM) tools.

Choose Create
Create Your Project Now

You will note that there is an “import from GitHub” button. SourceForge is where professionals go. GitHub is for hacks and kids still wet behind the ear. Yes, I have GitHub projects. They are things that got forked from other things that were on GitHub. In the case of the CppLinuxSerial I need to kill that unless I do more. The changes were almost instantly rolled into the base project. When I finally complete the others they will move to SourceForge.

Choose a Project Name and accept the URL
Actually create

Yes, you are going to be taken to that annoying “looks like your project is empty” page. Ignore it. You do need to select the project url and paste it into a text editor somewhere.

Now the real fun begins

Zip your entire directory tree up and copy it off some place for safe keeping. If you luggie this up you can at least get back to where you where.

Your personal project had a url underneath your user id because it was personal.

The personal project url
Edit hgrc and change the url

You will notice that I changed

default = ssh://roland_hughes@hg.code.sf.net/u/userid-2297536/csscintilla

to be

default = ssh://roland_hughes@hg.code.sf.net/p/csscintilla/csscintilla

because that is the project I created and the all lowercase name was the mountpoint.

I was a good little geek when making my changes. I put them all in my own branch. Mercurial is a bit picky about creating new branches with a push. It wants you to tell them you really mean it.

Now go back and look at the code in your project

You’ve got code!

My branch is there along with its new directories. Life is good . . . almost.

You still need to get updates from the base project

how to get stuff from base
hg pull http://hg.code.sf.net/p/scintilla/code -u

That pulls all of the stuff from the original scintilla base into my local working directory and project. It is not pulled into your branch! In particular the changes I wanted are in the default branch.

hg merge default
hg stat
hg addremove
hg commit --message "some message"

Let’s make it official

At this stage I have a shiny new SourceForge Mercurial based project called CsScintilla. My project really is just Scintilla at this point because all of my code is in CsScintilla branch. It is time for it to be an official project. Many thanks to Alexandra Zaharia for this nugget of information.

hg up default
hg merge CsScintilla    
hg ci -m "merge CsScintilla branch into default"
hg push
merging my branch into default

Be certain you wait for that repository refresh that got queued to finish. You should get an email notification. Once that happens you can take a look at default.

Success!

Life is good! The default branch now has my changes. Mercurial is cumbersome, but you can make it work.

Get rid of those unwanted branches

Last but not least we need to get rid of that development branch.

hg up CsScintilla
hg ci -m "closing CsScintilla development branch" --close-branch
hg addremove
hg stat
hg push

Yes, I did some technically unnecessary steps there, but I like to be thorough.

closing branch

Probably need a bit of explanation here.

Close closes the branch locally

SourceForge appears to have a much longer memory.

Roland Hughes started his IT career in the early 1980s. He quickly became a consultant and president of Logikal Solutions, a software consulting firm specializing in OpenVMS application and C++/Qt touchscreen/embedded Linux development. Early in his career he became involved in what is now called cross platform development. Given the dearth of useful books on the subject he ventured into the world of professional author in 1995 writing the first of the "Zinc It!" book series for John Gordon Burke Publisher, Inc.

A decade later he released a massive (nearly 800 pages) tome "The Minimum You Need to Know to Be an OpenVMS Application Developer" which tried to encapsulate the essential skills gained over what was nearly a 20 year career at that point. From there "The Minimum You Need to Know" book series was born.

Three years later he wrote his first novel "Infinite Exposure" which got much notice from people involved in the banking and financial security worlds. Some of the attacks predicted in that book have since come to pass. While it was not originally intended to be a trilogy, it became the first book of "The Earth That Was" trilogy:
Infinite Exposure
Lesedi - The Greatest Lie Ever Told
John Smith - Last Known Survivor of the Microsoft Wars

When he is not consulting Roland Hughes posts about technology and sometimes politics on his blog. He also has regularly scheduled Sunday posts appearing on the Interesting Authors blog.