GB rail electrification

Updating the site

Suggestions for small changes to both map data and these pages can be created using the GitLab web editor, and then discussed and merged as agreed, using the Git process commonly used in open-source software. Each merge recreates the files/web pages visible on the website. To make any changes, you must first be registered on GitLab.

Updating the text pages

  1. Each page (except the map) contains a link at the bottom "Suggest changes to this page"; clicking on this takes you to the source file on GitLab. The file is part of a collection of files called a 'repository' or 'repo'.
  2. Only those with write permissions can edit the file directly, so to edit it you first have to 'Fork', i.e. create a copy of the repo in your own account.
  3. When this is finished, you will see the source of the file you want to change. The pages are written in Markdown, a simplified way to create/edit the HTML markup used on the web. At the top, between 3 dashes, are some controls used for page generation; do not change these. (A WYSIWYG editor is under development, but not ready for use yet.)
  4. Scroll down to the place you want to edit, and make your changes. You can see the result rendered in HTML by clicking on 'Preview Markdown'.
  5. When finished, you can finalise your changes (called a 'commit'). This creates a new 'branch' in your copy of the pages, i.e. the 'master' copy remains as is, with your changes in a new copy. Enter a brief description of your change in the 'Commit Message' box, and then press 'Commit'.
  6. This will create the branch and go to the 'New Merge Request' screen. Here you can enter a more detailed description of your changes as appropriate. Clicking on the two 'Merge Options' keeps things tidy by deleting the branch when it's no longer needed, and 'squashing' (consolidating) later changes (see below) into one commit. Then press 'Submit Merge Request'. This adds a new entry in the Merge Request queue, and alerts the project owners that someone has submitted a proposed change. If the change is clear and undisputed, for example correcting a typo, it can be approved straightaway. Otherwise, others involved in the project can enter comments and the changes can be discussed as necessary, perhaps suggesting improvements. Click on 'Changes' at the top of any merge request to display the file(s) changed with the changes highlighted (called a 'diff', for 'difference').
  7. If changes to the merge request are needed, click on 'Web IDE', which will take you back to the editor, with the original version and your changes side by side, with the changed lines highlighted. Enter the revisions in the right-hand box, and then press 'Commit' again. You can then go back to the Merge Request page, which will now show your revised pages.
  8. Once the changes are agreed, the project owners can merge it into the original. The website pages will then be regenerated and the website updated accordingly (usually takes a minute or two).

This process means that, like a Wiki, anyone can suggest changes/improvements, but, unlike a Wiki, these can be discussed, and the original 'master' is only changed once everyone is agreed. Because the changes are checked before being merged, it is impossible to unintentionally mess things up. Even if changes are wrong, they can be changed with a further commit/merge, or even revoked by the repo owners if they're a total disaster.

For larger changes, where it's better to discuss first how best to improve something, go to the GitLab repo, click on 'Issues' on the left-hand menu, check a similar issue does not already exist (in which case, join in the discussion), and if not click on 'New Issue'. Anyone interested can then participate in the discussion and (hopefully) everyone can agree what to do.

Updating the map

What the map displays how is defined in configuration files in JSON format. This is essentially composed of 2 element types: arrays - comma-separated lists of double-quoted values delimited by []; and objects - comma-separated lists of key:value definitions delimited by {}. These are all in alphanumeric sequence to make values easy to find. The files are all in the tracks directory. config.json is the main file, which defines the directory where the main configuration files are, sub-divided into 'years', i.e. one set of config files for each year scenario. The basic structure does not change much, so the main changes involve the config files.

As the map explanation page states, the map lines are based on ELR codes. Common changes over time are:

The process for editing these files is similar to that for the text pages:

  1. Go to the config directory and pick the year directory you want to change.
  2. Click on the file you want to change, and then press either 'Edit' or 'Web IDE': 'Edit' is for changing a single file; 'Web IDE' gives you the ability to change more than one with one commit.
  3. Make the changes you want, for example by adding or deleting items, and then follow the same 'commit' and 'create merge request' steps as given from step 5 in the text pages section above.
  4. For example, if a freight-only line is being reopened for passenger use, this will generally be done in 2 stages: 1) when the decision to reopen has been made, the ELR needs to be removed from freight.json, and added to reopens.json; it can also be added to batteryLines.json; 2) when passenger use starts, it can then be removed from reopens.json. Similarly with electrification: 1) when a project is started, the ELR should be added to adjustelecs.json with a status of 'WIP', and removed from batteryLines.json; 2) then when the work is completed, the status should be changed to 'L' (for overhead line) or 'T' (for third-rail). In both cases, you have to make sure you keep the JSON structure; if you don't - for example, if you delete too many commas or brackets - the merge request will fail, and you will have to go back in and correct your commit. Computers are very pernickety about such things.
  5. In both these cases (reopens and electrification), if only part of an ELR is being changed, then the original line will have to be split. This is defined in splits.json, where each ELR to be split has an array of split points (as an ELR can be split into multiple sections), and each split point has a [longitude, latitude] coordinate plus the approximate mileage along the ELR. To find the coordinates, go to the map, zoom in to the place where you want to split the line, and place the cursor over the point. The decimal coordinates are displayed top right. As an extra complication, these are projected Cartesian coordinates, given by convention as x,y (lat,long), whereas geo coordinates, used in the split file, are given as long,lat. So the 2 have to be transposed before entering in the file. The approximate mileage of the split point can be obtained from Phil Deaves' site: go to the page for the ELR, find the junction or station corresponding to the split point, and use the mileage given. This is only for information and not used for any calculations, so does not have to be exact.

Larger changes involving the overall logic are best raised as issues on the GitLab repository.