How to update your published code

Introduction

TLDR

Update your published code as often as you feel the need to (managers discretion)
Keep the publishing code checklist in mind, though its up to your manager if a full check is required
A publish branch and merge requests helps you check only what has changed, saving time
when approved you can move your code over to the public repo (see the existing guidance)
consider using releases, semantic versioning and CHANGELOG.md

Why should we care?

Hopefully, all of our published code will be updated someday
on that day you might need this guidance

Pre-requisites

Pre-requisite	Importance	Note
Publishing Code in the Open	Necessary	You need to have done this before, or at least understand the process
Intro to Git	Necessary	There will be some use of GitHub and GitLab so knowing about Git is needed

After you've published your code for the first time, you may go on to do subsequent additions, changes and updates to the codebase held in our internal "development" repositories. It will then be time to update the code that has been published.

NHS England colleagues

See our internal confluence pages on "Git, GitLab and GitHub" which explains our internal setup.

This is pretty straightforward and follows the same process as described in "Publishing Code in the Open", however hopefully the guidance here will help you save time.

xkcd comic update

How to do the update

If you're developing your code on a private repo (either GitLab or Github), it's a good idea to keep a branch on your "development" repo which is identical to your public "publish" repo. This means that you can easily see what changes there are between your published code and the "main" branch of your development repo.

This means that when you are ready to update your published code:

First, in your private repo:

GitHubGitLab

do a pull-request (a.k.a. merge) from your main branch into your publish branch
if required by your manager, go through the "Publishing Code in the Open" process and checklist
- focus on just the things in the `pull-request' that have changed
when you're happy with the changes and they have been "approved" in the pull-request you can move the code from publish branch to the public repo (see the existing guidance)

do a merge-request (a.k.a. merge) from your main branch into your publish branch
if required by your manager, go through the "Publishing Code in the Open" process and checklist
- focus on just the things in the `merge-request' that have changed
when you're happy with the changes and they have been "approved" in the merge-request you can move the code from publish branch to the public repo (see the existing guidance)

It's good practice to make a new branch and do a pull-request in your public repo too, but you could also just make the changes directly to the main branch of the public repo.

Versioning and Changelogs

When you update your code, you've done the pull request, and it's all ready to be moved over to the public repo, it's a good time to tag the repo with a semantic version (in GitHub this can be done using the "release" functionality). You could also maintain a CHANGELOG.md so users can easily see what has changed since your last version release.

If you do a release with a version in the private repo, make sure you also release with the same version tag on the public repo.

How often to update the published code?

Main Points

ultimately it's up to the person who "owns" the codebase and the needs of the stakeholders
small changes can probably be batched up and then the published code updated less frequently

Each codebase (for a publication, package or whatever) will be different and will need changing at different rates, decided by the needs of the stakeholders, available resources and the person in charge of that codebase.

For example, for an annual publication, if some changes are made, might not be necessary to update the existing published codebase immediately, especially if they're small, minor fixed. However, If it's an important, change such as a new feature (i.e. some new metric) then it would probably help any stakeholders to see that published as soon as possible.

Useful Links

Last update: November 11, 2024

External Links Disclaimer

NHS England makes every effort to ensure that external links are accurate, up to date and relevant, however we cannot take responsibility for pages maintained by external providers.

NHS England is not affiliated with any of the websites or companies in the links to external websites.

If you come across any external links that do not work, we would be grateful if you could report them by raising an issue on our RAP Community of Practice GitHub.