Skip to content

Commit

Permalink
chore: add links to GitHub Desktop help pages
Browse files Browse the repository at this point in the history
  • Loading branch information
kshychko committed Nov 19, 2024
1 parent 94b900b commit f48e68b
Showing 1 changed file with 7 additions and 3 deletions.
10 changes: 7 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,17 @@ If you only need to make some very simple changes to an existing page (eg fix so
If you are going to be a regular contributor and/or you want to propose more significant multi-page changes in one request, then you should set yourself up with a local copy of the website where you can make as many changes as you like and test them before pushing a pull request to the main repository.

1. If you dont already have a GutHub Desktop client installed then get one from the [GitHub download site](https://desktop.github.com/download/). Sign into GitHub through your desktop (`GitHub Desktop` -> `Settings` -> `Accounts`). This will ensure that you can see all the GitHub repositories that you also have access to online.
2. Clone the UNTP repository using the `Add`->`Clone` button top left of your GitHub Desktop client. You'll need to choose a local folder to put your UNTP repository clone. We suggest you create a `GitHub` folder and keep all cloned repositories in it.
3. Once you've cloned the UNTP repository you'll see the full folder structure of the UNTP site under your `GitHub` local folder. Now you'll need to create your own branch in which to make changes. This is important - you should **not** make changes in the main branch as you will not be allowed to push them to the site. To make a local branch using your GitHub Desktop, make sure your current repository is `spec-untp` the then click on `current branch` and select `new branch`. Give it any name like "untp-spec-changes" and create the branch as a copy of `main`.
2. Clone the UNTP repository using the `File`->`Clone Repository...` button top left of your GitHub Desktop client. You'll need to choose a local folder to put your UNTP repository clone. We suggest you create a `GitHub` folder and keep all cloned repositories in it.
> *Checkout GitHub Desktop [Cloning a repository](https://docs.github.com/en/desktop/adding-and-cloning-repositories/cloning-and-forking-repositories-from-github-desktop#cloning-a-repository) help page for step-by-step instructions.*
3. Once you've cloned the UNTP repository you'll see the full folder structure of the UNTP site under your `GitHub` local folder. Now you'll need to create your own branch in which to make changes. This is important - you should **not** make changes in the main branch as you will not be allowed to push them to the site. To make a local branch using your GitHub Desktop, make sure your current repository is `spec-untp` the then click on `current branch` and select `new branch`. Give it any name like "untp-spec-changes" and create the branch as a copy of `main`.
> *Checkout GitHub Desktop [Creating a branch](https://docs.github.com/en/desktop/making-changes-in-a-branch/managing-branches-in-github-desktop#creating-a-branch) help page for step-by-step instructions.*
4. Now you have two branches - `main` and your local branch. When you select any branch, GitHub will ensure that the files you synchronised to your local folder are for that branch. So you always work on the same folder structure but the files you see will relfect the state of whichever branch you have selected in your Desktop client.
5. You'll find the files that you need to change by navigating `spec-untp`->`website`->`docs`. There you'll see a list of folders that correspond to the UNTP site structure (about, specification, etc). Inside each folder is an `index.md` file - that's the content that appears at the heading level (eg [Business Case](https://uncefact.github.io/spec-untp/docs/business-case/)). Inside that folder you'll see the files that represent the pages under that heading. Any files with a `.md` suffix are the Markdown files that hold the text fot that page. Any other files such as `.png` files contain images that are referenced from that page.
6. Make the changes you need to make to the files using any editor you like, ([Sublime Text](https://www.sublimetext.com/download)) is not a bad option. At this point we **strongly recommend** that you have a local copy of the website running on your laptop - follow the instructions for [setting up the local website](running-a-local-untp-website) below. Whenever you save a change to a `.md` file you should immediately see that change reflected on your local UNTP website copy. This is a good way to test that your changes look right and there aren't broken links.
7. If you have a large amount of change to many un-related pages then we suggest that you create a separate branch for each. But lets keep it simple for now and assume you've changed a page or two. Then `commit` those changes in your local GitHub Desktop and provide a commit message just like you did for the online [simple changes](#simple-changes) edit. That will save create a versioned change on your local GitHub.
8. Now create a `pull request` on your desktop. That will trigger the creation of a pull request on the "origin" GitHub repository where UNTP is maintained. You'll be redirected to the UNTP GitHub site online and will see the same pull request screen that you saw with the [simple process](#simple-changes) described above.
> *Checkout GitHub Desktop [Write a commit message and push your changes](https://docs.github.com/en/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop#write-a-commit-message-and-push-your-changes) help page for step-by-step instructions.*
8. Now create a `Pull request` on your desktop. That will trigger the creation of a pull request on the "origin" GitHub repository where UNTP is maintained. You'll be redirected to the UNTP GitHub site online and will see the same pull request screen that you saw with the [simple process](#simple-changes) described above.
> *Checkout GitHub Desktop [Creating a pull request](https://docs.github.com/en/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/creating-an-issue-or-pull-request-from-github-desktop#creating-a-pull-request) help page for step-by-step instructions.*
9. You're done - your changes will be verified and queued for approval.

## Running a local UNTP website
Expand Down

0 comments on commit f48e68b

Please sign in to comment.