Contributing to projects on GitHub with Subversion

git, GitHub, SCM, subversion, TortoiseSVN 3 Minutes

Edit: On 2023-01-20 GitHub announced that they will stop supporting Subversion on 2024-01-08.
— 2023-04-18 twm

Many open source projects have moved from the former top dog SlashdotSourceForge to GitHub and in the process usually converted from Subversion to git. This also includes quite a few Delphi libraries like project Jedi (JCL/JVCL), SynEdit or Indy.

I am not really comfortable with git, it just feels too complex for most projects and the GUI tools I have tried are clunky compared to TortoiseSVN. I see some advantages, but so far I’m not convinced. So, I have stayed with SVN and used that to access GitHub repositories through their git-svn bridge. This works fine, most of the time, unless you want to rename a file, which apparently is not possible for whatever reason.

Now, contributing to such projects is another challenge. You need to create something called “pull requests“, which basically is a way of creating patches that are centrally managed by GitHub together with a discussion area for them. It took me a while to get my head around the process but I think I got it now. So here are the steps:

  1. Get a GitHub account. There is no way around that.
  2. Fork the repository of the project to which you want to contribute.
  3. Create a branch in that forked repository. You need a separate branch for each pull request you want to create! (That was the main stumbling block for me, I just didn’t realize this. It’s probably documented somewhere but I overlooked it.)
  4. Check out that branch.
  5. Make your changes in that branch
  6. Commit those changes and push them to GitHub
  7. On GitHub, create a pull request

There are many sites that give you these steps sometimes with examples on how to do them, but always using git. Here is, how to do it without a git client, but using svn + the aforementioned git-svn bridge.

GitHub shows a url for each repository that can be accessed via git or svn. It looks like this:

https://github.com/[account]/[project].git

Remember that this url contains the the whole repository, so in order to check out only the trunk (master branch) or a branch, you need to add /trunk or /branches/[branchname] to it.

Creating a branch can be done either with svn in the usual way or with the web UI on GitHub. I prefer the latter which is done by typing a non-existing name for a branch and pressing enter.

For the following steps lets assume we created a branch called “pullrequesttest”.

Using the svn client of your choice (mine is TortoiseSVN), check out the sources of the branch we just created. The url would be:

https://github.com/[account]/[project].git/branches/pullrequesttest

Just make your changes and commit them the usual way. Subversion does not distinguish between a commit and a push to the server as git does.

The branch now contains the changes you want to submit to the project.

On GitHub, select that branch and you will see a message about your changes an a button “Compare & pull request”.

Click that button, add a comment and submit the pull request. It should show up on the original project’s page. Somebody with the rights to it can now approve and merge these changes. They can also be discussed there. Maybe some further improvements are necessary to get them accepted. For that you simply make changes to the code you have checked out and commit them to the same branch. They will automatically become part of the pull request (Remember that I said you need a separate branch for each pull request? That’s why.).

Now suppose there are other, unrelated changes you would like to submit? Start with creating a new branch, based on master, check out the code, make the changes commit them and create a new pull request for the new branch.

Just remember to never make any changes to the trunk (=master branch). That one is meant to have the same content as the original repository and the base for each branch to be used for a pull request.

I’m sure this description is more complicated that it needs to be. My main idea in writing this article is to get a starting point for creating pull requests without having to use git. If you can think of improvements, please discuss them in Delphi Praxis. Note that this is not meant to become a discussion about the merits of git vs. Subversion. We don’t need another one of these.

Published