Forking and website creation steps

How to fork a repo

1. Go to the otn-workshop-base repository homepage

2. In the top right-hand of the page (just under the profile picture), click the 'Fork' button (between "Unwatch" and "Star").

3. Make sure the 'Owner' is set to 'ocean-tracking-network.'

4. Give the repo a meaningful name. Typical format is yyyy-organization-subject-workshop, where yyyy is the year the workshop is taking place, organization is the audience to whom we're giving it, and subject is the course material we're teaching.

5. Provide a useful description.

6. Make sure to uncheck the 'Copy the gh-pages branch only.' You will need both master and gh-pages in your new fork.

7. Click Create Fork.

How to stand up the website

1. In your new fork's repo site, go to the "Settings" tab (it's just under the 'Unwatch' button next to the 'Fork' button).

2. In the left sidebar of that page, click the 'Pages' tab.

3. Under the 'Source' section, set the source branch to gh-pages (the folder will default to /(root), this is fine). Click 'Save'. This step will happen automatically when you push a commit to gh-pages, but it's fine to do it manually too.

4. The site will now be published at the link on this page (in the highlighted box at the top of the settings). Note that it may take a while for the site to be visible, depending on your caching settings. Give it about 15 minutes.

Notes

1. Forking gives us the ability to sync upstream changes (i.e, changes to the main otn-workshop-base repo), meaning we can more easily sync changes across workshop repos when necessary. However, workshop sites made before the writing of this article (July 12, 2022) do not have that functionality, because I made them using the Github Importer. This is because the Carpentries sites recommend you use the importer so they don't get swamped with notifications from everyone's forks. I got used to doing it that way until just now, when I did some research and realized that for us, we have less reason not to just fork. So, going forward, the above method is how we'll do it. Although we're not terribly interested in maintaining previous workshops, this will make it easier if we want to, say, dust off a curriculum and reuse it. At the very least, it's a little faster than the importer and requires fewer clicks.

2. Forking preserves all of the branches from the original repo. This is good since it means we don't have to recreate the gh-pages or master branches, but it does mean that the new repo will have all of the issue branches that we use while we're working. This isn't a huge problem, necessarily, but it's worth it to be aware of for efficiency's sake. All the more reason to delete branches as we merge and keep the repo clean.