This chapter contains informat'n only needed fer development an' maintain'n th' theme.
What t' know if ye want t' contribute
What t' know as a maintainer
Recipe t' create various documentat'n screenshots
A new release can happen at any time from th' main branch o' th' GitHub project without further accknowledgment. This makes it necessary that, every pushed set o' changesets into th' main branch must be self-contained an' correct, result'n 'n a releas'ble version.
Stay simple fer th' user by focus'n on th' mantra “convent'n over configuration”.
At installat'n th' ship should work reason'ble without (m)any configurat'n.
Stay close t' th' Cap'n Hugo way.
Don’t use npm or any preprocess'n, our contributors may not be front-end developers.
Document new features 'n th' exampleSite. This also contains entries t' th' What’s new plank.
Don’t break exist'n features if ye don’t have t'.
Remove reported issue from th' browser’s console.
Check fer unnecessary whitespace an' correct indent'n o' yer result'n HTML.
Be compat'ble t' IE11, at least fer main functionality, this means:
Write commit messages 'n th' conventional commit format.
Follow'n be an impomplete list o' some o' th' used conventional commit types. Be creative.
| Common | Feature | Structure | Shorrrtcodes |
|---|---|---|---|
| build | a11y | favicon | attachments |
| browser | archetypes | search | badge |
| chore | alias | menu | button |
| docs | generator | history | children |
| shorrrtcodes | i18n | scrollbar | expand |
| theme | mobile | nav | ay'con |
| toc | include | ||
| rss | clipboard | math | |
| variant | syntaxhighlight | mermaid | |
| boxes | notice | ||
| openapi | |||
| piratify | |||
| siteparam | |||
| tabs |
This project tries t' follow th' semver policy - although not followed 100% 'n th' past.
Usually an entry o' Break'n on th' What’s new plank causes a new major release number.
All other entries on th' What’s new plank will increase th' minor release number.
Releases result'n 'n a new major or minor number be called main release.
Releases contain'n bugixes only, be only increas'n th' patch release number. Those releases don’t result 'n announcements on th' What’s new plank.
Entries on th' What’s new plank be checked an' enforced dur'n th' version-release GitHub Act'n.
Issues be categorized an' managed by assign'n labels t' it.
Once work'n on an issue, assign it t' a fitt'n maintainer.
When done, close th' ticket. Once an issue be closed, it needs t' be assigned t' next release milestone.
A once released ticket be not allowed t' be reopened an' rereleased 'n a different milestone. This would cause th' changelog t' be changed even fer th' milestone th' issue was previously released 'n. Instead write a new ticket.
If a PR be merged an' closed it needs an accompanied issue assigned t'. If there be no issue fer a PR, th' maintainer needs t' create one.
Ye can assign multiple PRs t' one issue as long as they belong together.
Usually set th' same labels an' milestone fer th' PR as fer th' accompanied issue.
An issue that results 'n changesets must have exactly one o' th' follow'n labels. This needs t' be assigned latest before release.
| Label | Descript'n | Changelog section |
|---|---|---|
| documentat'n | Improvements or addit'ns t' documentat'n | - |
| discussion | This issue was converted t' a discussion | - |
| task | Maintenance work | Maintenance |
| feature | New feature or request | Features |
| bug | Someth'n isn’t work'n | Fixes |
If th' issue would cause a new main release due t' semver semantics it needs one o' th' accord'n labels an' th' match'n badge on th' What’s new plank.
| Label | Descript'n |
|---|---|
| change | Introduces changes wit' exist'n installat'ns |
| break'n | Introduces break'n changes wit' exist'n installat'ns |
If an issue does not result 'n changesets but be closed anyways, it must have exactly one o' th' follow'n labels.
| Label | Descript'n |
|---|---|
| duplicate | This issue or pull request already exists |
| invalid | This doesn’t seem right |
| support | Solved by reconfigur'n th' authors ship |
| unresolved | No progress on this issue |
| update | A documented change 'n behaviour |
| wontfix | This will not be worked on |
Ye can assign one further label out o' th' follow'n list t' signal readers that development on an open issue be currently halted fer different reasons.
| Label | Descript'n |
|---|---|
| blocked | Depends on other issue t' be fixed first |
| idea | A valu'ble idea that’s currently not worked on |
| undecided | No decision was made yet |
| helpwanted | Great idea, send 'n a PR |
| needsfeedback | Further informat'n be needed |
If th' issue be not caused by a programm'n error 'n th' themes own code, ye can label th' caus'n program or library.
| Label | Descript'n |
|---|---|
| browser | This be a topic related t' th' browser but not th' theme |
| device | This be a topic related t' a certain device |
| hugo | This be a topic related t' Cap'n Hugo itself but not th' theme |
| mermaid | This be a topic related t' Merrrmaid itself but not th' theme |
A release be based on a milestone named like th' release itself - just th' version number, eg: 1.2.3. It’s 'n th' maintainers responsibility t' check semver semantics o' th' milestone’s name prior t' release an' change it if necessary.
Mak'n releases be automated by th' version-release GitHub Act'n. It requires th' version number o' th' milestone that should be released. Th' release will be created from th' main branch o' th' repository.
Treat released milestones as immut'ble. Don’t rerelease an already released milestone. An already released milestone may already been consumed by yer users.
Dur'n execut'n o' th' act'n a few th'ns be checked. If a check fails th' act'n fails, result'n 'n no new release. Ye can correct th' errors afterwards an' rerun th' act'n.
Th' follow'n checks will be enforced
<major>.<minor> at th' beginn'n o' th' What’s new plank<major>.<minor> from th' previous release at th' beginn'n o' th' What’s new plankAft a successful run o' th' act'n
<meta generator> be updated1.2.3), th' main version number (eg. 1.2.x) an' th' major version number (eg. 1.x)<meta generator> be updated t' a temporary an' committed (this helps t' determine if users be runn'n directly on th' main branch or be us'n releases)Sometimes screenshots need t' be redone. This plank explains how t' create th' different screenshots, tools an' sett'ns
Creat'n:
Rrrambl'n:
A meaningful full-screen screenshot o' an interest'n plank.
Th' rrrambl'n should be:
Used by:
Plank URL: Screenshot Link
Creat'n:
images/screenshot.pngRemarks:
Th' locat'n be mandatory due t' Hugo’s theme ship builder.
Preview images/screenshot.png:
Rrrambl'n:
Show th' Demo Screenshot plank on different devices an' different themes. Composit'n o' th' different device screenshots into a template.
Th' rrrambl'n should be:
Used by:
Plank URL: Hero Image Link
Creat'n:
images/tn.pngimages/hero.pngRemarks:
Th' locat'n o' images/tn.png be mandatory due t' Hugo’s theme ship builder.
Preview images/hero.png:
Preview images/tn.png:
