Editing a string using a pull request
We use pull requests to prevent issues if more than one person is working on a string, and to help us track what is happening.
This creates your own "copy" of the file, which will be merged with the main version once you are done.
Open the file you want to work on. To the top left, in the "Files" menu, click on the dropdown button where it says "main", and in "Find or create a branch..." type the name of your branch. Click on the option that comes up, "Create branch [your name] from main". You can call it anything you want, but a good principle might be your name and an indication of what you are working on (for example "caroline sdg02" for multiple changes to this SDG, or "caroline SDG2.3" for target 3).
-
Check that your new branch is selected in the dropdown menu (where it said "main" before). This means that when you open the editor, you will be editing on your branch.
-
Click on the drop down editing button (pen) to the top right, and "Open in github.dev"
The advantage of using github.dev is a) code highlighting (helps us to spot missing boolean operators or quotation marks), and b) we can edit two files at the same time (if we want to make changes to action and topic in one commit).
Features useful to know about:
- a) To the right you can see a preview of the whole file, which you can use to navigate up and down
- b) To the left you can see all the files in the repository. The one open right now is highlighted, but if you wanted to work on topic at the same time, you can open it in a new tab in the same editor
- c) Files get an "M" symbol next to them in the file overview if you have made any changes
- d) Right at the bottom left, you can see in small text which branch you are on
- e) Add a "py" after the ``` (which open a code block) in order to turn on code highlighting for that block. In the code below you can see the first code block has code highlighting on, while the second does not.
- f) You can use ctrl+f to open "find and replace", super helpful for changing terms in multiple targets
- g) Use the "tab" key to get nice neat indenting of the code
Once you have edited, you will see that a yellow number will appear on the branch symbol to the far left - the number of files you have changed during this session. When you are finished, click on that symbol and it will open the menu to make a commit (save your changes and push them to the branch). You will see a text field, and the files you have changed listed below.
There are 2 steps to saving in GitHub - committing and pushing. Committing can be thought of as save, while pushing uploads your save to the branch. In this menu we can do both at once, as the default button says "Commit & push".
- First we should write a commit message, which is a short summary of what we changed during this commit. You have seen these messages when looking at files in the repo, where the last message is shown for each file. For example, you could write "edited 2.3" for working on target 1.5, or "added documentation" if adding general documentation for the whole SDG. It is just a note to help us navigate if we ever have to go back.
- Next, double check that you are on your branch
- Click on the "Commit & push" button. Your changes are saved and pushed! And the files will disappear from this list.
If you want to make more changes, just keep working in the files (the tabs will still be open). When you are done, repeat the process above.
To go and check back in the repository, if you have closed the window, just use the button called "Go back to repository"
We can just keep working on our own individual branches over time. You can revisit a branch whenever you want until it is merged with "main" (the main version). This might be a good idea if we are working on individual targets each.
In general it might be good to open a "pull request" after your first session on a branch. You generally will get a suggestion to do this for any branch you have just edited. Click on the "Compare & pull request" button to open a pull request.
To create the pull request, you should give it a title that explains what it is about (e.g. First draft 2.3 and 2.8). In the "description" you can describe more thoroughly if needed. This is likely not needed for first drafts, but might be needed when editing after review (we might want to describe which things we have changed and why), or if fixing "Issues" opened in the repository (we can link to an issue that has been fixed by the PR and it will close the issue). Further down on the page, we can see a list of the commits we have made, and what has been changed between our branch and main highlighted in red and green. Click on "Create pull request" when done. Note that it can be edited after too :)
After it is created, we can still work on the branch and add new commits. These will be added to the pull request. We can also add new comments to the pull request, and other people can comment on it too.
When we are finished with a branch (e.g. we are done with a version of a target) and want to merge it into main, then we can tell someone else that we want a "review" (and tag them in the top right corner). It will not be merged and closed until we click on "Merge pull request", and we will not do this until we have confirmed this with each other. This requires a "review" from someone else too, so you can't really go wrong :)
For a good example of pull requests that we have used in the past, updated after opening, linked to issues, and finally merged with main, check out an old one like this https://github.com/SDGforskning/sdg-strings/pull/124
This is maybe a matter of taste that we will have to figure out. But I suggest that we don't try and do too much one one branch and have a low threshold for merging.
For example, if you have a finished draft of a target, I suggest merging. Then, if you want to make further changes, or if someone else wants to work on it, you/they open a new branch.