Git cheatsheet

Using Git to develop RISC OS

The source code to RISC OS in held in a version control system called Git, making it easy to see who changed what and why. Everyone can take a look around by going to the ROOL gitlab. To be able to make edits to the code you’ll first need to create an account then log in.

The remainder of this page describes how to work with Git to propose changes to RISC OS, if you only want to browse, go exploring!

Using Git as a developer

Introduction

At present there’s no mature Git client that runs on RISC OS directly, so the step involving Git requires the client to be run on another computer such as a Linux, Windows or Mac. Note that this doesn’t necessarily need to be a traditional computer: you could use a NAS or a Raspberry Pi running Raspbian, for example.

For very simple edits, you can even use the GitLab web interface on a supported browser. However, because this would mean you’ve not tested the change on RISC OS, this isn’t a recommended method of working.

To compile the sources you’ll need the Desktop Development Environment (DDE) and a means of running that on RISC OS itself. You can do this using an emulator, in which case you need to do your Git operations within a directory that is visible from the emulator. Otherwise, you need to use a file sharing protocol (such as SMB or NFS) to enable files to be transferred to and from your RISC OS machine. A recent native RISC OS machine will typically be many times faster than an emulator, so is the preferred option if you will be doing repeated incremental builds.

Organisation of the sources

The sources are arranged in a hierarchy:

Also at the top level are some non-source files in supporting roles:

For some of the simpler components, the DDE contains everything you need to build the component in isolation. In this case, you can fetch just that one component. If you know the name of the component you would like to work on, but don’t know where to find it, you can go to the Explore projects page and use the “Filter by name” box to search for it. If you’re totally lost, the build system itself looks up the location of a component in the ModuleDB which will direct you where to go beneath the top level of RiscOS.

A product, such as a ROM image or a disc image, comprises multiple components and we’ve organised these into super-projects available under the Products hierarchy. These refer to whichever components are needed to complete the build. For most intents and purposes, you can interact with each of these components in the same way and using the same tools as any other Git repository.

Basic operations

Cheat sheet

Use the following as a reminder of how to perform the most common operations.

• Workflow via Linux, the command line, and NFS
  • Get sources to a single component
  • Getting the latest sources to an entire product to build on RISC OS
  • Getting the source to a particular version of a build
  • Viewing the history of my local source tree
  • Local setup before you start to make changes
  • Recording your changes locally
  • Updating your clone with the latest version
  • Submit changes for review
• Workflow via Windows, TortoiseGit, and SMB
  • Get sources to a single component
  • Getting the latest sources to an entire product to build on RISC OS
  • Getting the source to a particular version of a build
  • Viewing the history of my local source tree
  • Local setup before you start to make changes
  • Recording your changes locally
  • Updating your clone with the latest version
  • Submit changes for review
• More advanced topics
  • Working with superprojects
  • Tips and tricks for pro users

Look at the current reviews and comment on one

On the top bar of every GitLab screen is an icon depicting a merge. Click on this to search merge requests. You can filter merge requests in a number of ways. If you want to see a complete list, you can try a search term of Assignee:any.

Create a completely new component and submit it for review

Simply email a web link to code@riscosopen.org. Any Git hosting site will do, since we will copy the repository history but change the GitLab settings for consistency with our other projects.

You may wish to use our GitLab installation to host your component, not least because it offers RISC OS-specific syntax highlighting that is not available elsewhere. To do this, find the + button at the top of any page, choose New project and follow the instructions.

Guidance on a good merge request

Merge requests are the means by which developers can propose changes to the RISC OS source code and while the acceptance rate is relatively high, there’s no guarantee that the change will be accepted following review. Here are a few guidelines on what makes a ‘good’ merge request, and a few things to avoid.

• Consider breaking up large/complicated changes into a set of smaller commits, this makes them easier to review
• Try to follow the layout style of the existing source code, such as placement of braces and indentation
• Collect related commits together in one merge request, rather than opening several each with only one change
  • Use the summary paragraph to describe why they go together and to ‘sell’ the benefit of the submission as a whole
  • See if there’s another similar merge request pending for that component, it may be worth collaborating with that developer on the same area
  • We don’t offer a prize for most merge requests opened!
• Generally, the following classes of changes are unlikely to be accepted
  • Merge requests that merely churn the code without substance, because they confuse the change history (for example, lowercasing all comments in a component)
  • Merge requests that only benefit one port to the detriment of others (for example, slowing down the Kernel’s SWI despatch in order to support an emulator)
  • Merge requests that contain debug or temporary code left enabled; remember to diff your changes before committing and remove any remnants