Add guide for creating new prototypes (using the GitHub template) #391
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This adds a guide to for creating a new repository using the GitHub website template repository feature. We’ve found this to be a lot simpler and easier than explaining how to download the kit and then later sync it with a new empty repository on GitHub. It also avoids a common mistake people make which is to clone the repository instead, and then get an error when trying to sync it as they do not have permissions to push.
Existing one was showing using Codespaces on the template repository itself, rather than on a prototype created using the template.
This updates the existing Mac and Windows install guides to reference the new guide for creating a new prototype.
This references the new guide to using the template repository.
colinrotherham
temporarily deployed
to
nhs-prototyp-add-create-7qnp9w
frankieroberto
requested review from
LauraJD,
anandamaryon1,
paulrobertlloyd and
sarawilcox
| Alternatively if you use Visual Studio Code you can open a new window and select ‘Clone Git Repository’ and then paste in the URL of your prototype on GitHub. | ||
|
|
||
|  | ||
| You can also click the ‘Code’ button and select the ‘Download ZIP’ option – however if you do this you will not be able to synchronies your changes as easily. |
Contributor
There was a problem hiding this comment.
Is this true or is it more accurate to say:
Suggested change
| You can also click the ‘Code’ button and select the ‘Download ZIP’ option – however if you do this you will not be able to synchronies your changes as easily. | |
| You can also click the ‘Code’ button and select the ‘Download ZIP’ option – however if you do this you will need to manually link, or initialise, your prototype kit folder with Git. |
Maybe gives enough detail for someone to be able to Google how to do this?
Maybe not important?
| Here’s how to complete the fields: | ||
|
|
||
| * **Include all branches**: leave this in the ‘off’ setting | ||
| * **Owner**: this should be the name of the organisation you are working for. If you have not yet been added to your organisation on GitHub you should ask to be added. |
Contributor
There was a problem hiding this comment.
Maybe mention that if you're just trying it out, you can make it personal? Or maybe that's obvious?
Contributor
Author
There was a problem hiding this comment.
Good point! Could also say that you can change the owner later if needed.
| * **Owner**: this should be the name of the organisation you are working for. If you have not yet been added to your organisation on GitHub you should ask to be added. | ||
| * **Repository name**: this should be the name of the service you are prototyping. You can change this later if you are not yet sure of the name. By convention it is lowercase and uses hyphens instead of spaces. Add the suffix `-prototype` to make it clear to others in your organisation that it is a prototype. | ||
| * **Description**: this is optional and you can leave it blank for now, or enter a short description of what the service you are prototyping will do. | ||
| * **Choose visibility**: You can choose to make your prototype code public or private. This can be changed later. |
Contributor
There was a problem hiding this comment.
Could say: by default public sector work should be open source, so make it public unless you expect to have sensitive information in it. For example, it's related to an unannounced policy.
Contributor
|
This is great, it's simpler and ties in nicely with the codespaces guide too. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The existing Mac, Windows and Advanced getting started guides suggest that users download the zip file containing the prototype or do a ‘Clone’ of the project from GitHub.
The problem
Both of these options can cause some issues, particularly for new users unfamiliar with Git and Github:
There can also be issues on Windows with the
.gitignorehidden file not being copied, and then accidentally later committing thenode_modulesfolder.nhsuk-prototype-kitthen you’ll likely end up with errors if you try to push it you won’t have permission. Instead you could fork the project first, but then that will clone all branches, and you’ll likely then later get prompted by GitHub to open a pull request from your fork to the main template repository.New approach
The new approach is the one outlined in the existing guide to using GitHub Codespaces, which is to create a new repository on GitHub using the
nhsuk-prototype-kitproject as a template.This has the advantage of doing all the GitHub repo setup for you, giving you a copy of the prototype kit with no history attached and everything committed under a singe 'Initial commit'.
The project also retains a link back to the template repository via a 'Generated with...' link:
This approach has been tried and tested with 46 participants in the NHS prototype kit training course, and has worked well!
The only downside I can think of is that it assumes you’re using GitHub to host your code, rather than an alternative like GitLab - but that’s relatively rare and if you’re doing that you can probably work it out? The Advance install guide still contains a link to the Zip file for those who want it.
The future
Using the template repository will work even better from version 8 onwards, as at that point the template repository can become much simpler and more template-like, as the main code of the kit will be within a separate npm package that the template uses.
See nhsuk/nhsuk-prototype-kit#688 for work in progress.