Here's a checklist for Contributors and Maintainers, using Github workflow. The examples all assume you've added a github ssh key.
- Contributors and Maintainers Defined
- Fork the repo
- Add a ref to the upstream repo
- Make a feature branch
- Make your changes
- Test your changes
- Commit your changes and push to your repo
- Submit a Pull Request
- Alternative approach: Editing in the browser on GithHub
- Maintainer Only: Review and Merge Pull Request
- Maintainer Only: Publish
Anybody can be a Contributor. Follow the next steps to fork the repo, make a feature branch and submit a pull request (PR).
Maintainers have permissions to review and merge PRs into the master branch and to publish to the release branch.
If you are new to maintaining the docs, perform this one-time task:
Fork your own copy of the repo. In the examples below, I call it my-repo.
Go to https://github.com/HamStudy/examtools-docs and click Fork.
Once you've forked it, you can clone it locally to your desktop, following the instructions provided.
$ git clone [email protected]:myname/examtools-docs.git my-repo
$ cd my-repo
Your clone of the repo will have the default remote name of origin.
$ git remote -v
origin [email protected]:myname/examtools-docs.git (fetch)
origin [email protected]:myname/examtools-docs.git (push)
Add a reference to upstream so you can keep your fork in sync.
$ git remote add upstream [email protected]:HamStudy/examtools-docs.git
$ git remote -v
origin [email protected]:myname/examtools-docs.git (fetch)
origin [email protected]:myname/examtools-docs.git (push)
upstream [email protected]:HamStudy/examtools-docs.git (fetch)
upstream [email protected]:HamStudy/examtools-docs.git (push)
Any time you want to get up-to-date with the latest changes, git pull upstream master:
$ git checkout master
$ git pull upstream master
remote: Enumerating objects: 1, done.
remote: Counting objects: 100% (1/1), done.
remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (1/1), done.
From github.com:HamStudy/examtools-docs
* branch master -> FETCH_HEAD
03a0672..fca28f5 master -> upstream/master
Updating 03a0672..fca28f5
Fast-forward
content/docs/cve/_index.md | 2 --
1 file changed, 2 deletions(-)
To keep your fork of the repo current, you can push to it (note that the first time you use this shortcut flavor
of git push you'll be prompted to do a longer command: git push --set-upstream origin master.
From then on just git push pushes to your repo).
$ git push
Total 0 (delta 0), reused 0 (delta 0)
To github.com:myname/examtools-docs.git
03a0672..fca28f5 master -> master
Now that your fork is current with the master branch, make a new feature branch to hold your changes.
$ git checkout -b my_feature
Switched to a new branch 'my_feature'
The web site content is in the content directory tree.
Do some editing of the content files as needed. For example, I want to make some changes to the ARRL CVE checklist:
$ emacs content/docs/cve/arrl/checklist.md
Hugo uses the front matter tags to do things like sort the documents in the lefthand menu (weight tag)
and to set the last update date of the file (date tag). However, if you leave the date out, then
it will be set to the date of the git commit for the file. This is probably what you wanted and eliminates
the need to manually update this field every time you edit a given file. If you want to force the date
to be something other than the git commit date, then set the tag explictly.
This is especially useful for the RSS feed since feed readers will notify subscribers of new updates automatically:
Here's an example of the front matter for one file with the date commented out:
---
# Title, summary, and page position.
linktitle: VE Roles and Permissions in an ExamTools session
weight: 30
featured: false
draft: false
icon: book-reader
icon_pack: fas
# Page metadata.
title: VE Roles and Permissions in an ExamTools session
#date: "2012-12-11T00:00:00Z"
type: book # Do not modify.
---
One time: See the instructions for installing Hugo locally.
For example, on a Mac with homebrew.
brew install git golang hugo
Then run the Hugo server to view your newly updated site:
$ hugo server
hugo: downloading modules …
hugo: collected modules in 2778 ms
| EN
-------------------+-----
Pages | 31
Paginator pages | 0
Non-page files | 8
Static files | 5
Processed images | 19
Aliases | 4
Sitemaps | 1
Cleaned | 0
Built in 292 ms
Watching for changes in /Users/myuser/my-repo/{assets,content,data,static}
Watching for config changes in /Users/myuser/my-repo/config/_default, /Users/myuser/my-repo/go.mod
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at //localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop
And open http://localhost:1313/ in your browser.
Rinse and repeat until your changes look right.
You can also run ./view.sh which does hugo server --disableFastRender --i18n-warnings -p 1316.
$ git status
On branch my_feature
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: _index.md
no changes added to commit (use "git add" and/or "git commit -a")
$ git add _index.md
$ git commit -m 'a useful short description here'
[my_feature 7701f9c] a useful short description here
1 file changed, 37 insertions(+), 34 deletions(-)
$ git push
fatal: The current branch my_feature has no upstream branch.
To push the current branch and set the remote as upstream, use
git push --set-upstream origin my_feature
$ git push --set-upstream origin my_feature
Enumerating objects: 13, done.
Counting objects: 100% (13/13), done.
Delta compression using up to 8 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (7/7), 1.82 KiB | 1.82 MiB/s, done.
Total 7 (delta 3), reused 0 (delta 0)
remote: Resolving deltas: 100% (3/3), completed with 3 local objects.
To github.com:myname/examtools-docs.git
700e65d..7701f9c my_feature -> my_feature
Enumerating objects: 11, done.
Counting objects: 100% (11/11), done.
Delta compression using up to 8 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 1.30 KiB | 1.30 MiB/s, done.
Total 6 (delta 2), reused 0 (delta 0)
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
remote:
remote: Create a pull request for 'my_feature' on GitHub by visiting:
remote: https://github.com/myname/examtools-docs/pull/new/my_feature
remote:
To github.com:myname/examtools-docs.git
* [new branch] my_feature -> my_feature
Branch 'my_feature' set up to track remote branch 'my_feature' from 'origin'.
Now go to the above URL in your browser and you can submit a PR.
You can also edit pages directly in the web browser on github.com. When ready to save your edit, in the Commit Changes
box at the bottom of the page, select "Create a new branch for this commit and start a pull request" rather than
the default to "Commit directly to the master branch." Choose a descriptive name for your update or just let
GitHub pick a boring one like "user-patch-1."
The main drawback of this approach is you can't test your updates locally via Hugo, but this is way simpler!
As a maintainer you can review the PR, request changes, approve, etc. and then merge it to master.
Publishing to https://docs.exam.tools/ only happens when you push the master to the release branch.
cd my-repo
git checkout master
git pull upstream master
git push upstream master:release