T' chapterrr 5

Development

This chapter contains informat'n only needed fer development an' maintain'n th' theme.

Contribut'n

What t' know if ye want t' contribute

Maintain'n

What t' know as a maintainer

Screenshots

Recipe t' create various documentat'n screenshots

Subsct'ns o' Development

Contributing

Code Quality

A new release can happen at any time from th' main branch o' th' GitHub project without further acknowledgment. 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' docs. 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.

Conventional Commits

Write commit messages 'n th' conventional commit format.

Follow'n be an incomplete 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
print toc include
rss clipboard math
variant syntaxhighlight mermaid
boxes notice
openapi
piratify
siteparam
tabs

Maintaining

Semver

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 bugfixes 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.

Manag'n Issues

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.

Manag'n Pull Requests

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.

Labels

Kind

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

Impact

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

Declinat'n

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 Request fer achiev'n a special goal
unresolved No progress on this issue
update A change 'n behavior after updat
wontchange This will not be worked on

Halt

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

3rd-Party

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
asciidoc This be a topic related t' process'n o' AsciiDoc
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

Sett'n Up a Development Environment

Git Hooks be used t' automate some tasks. They be stored 'n th' .githooks root folder.

Documentat'n fer each hook be contained 'n each file.

At least th' pre-commit hook be required, as it updates th' version number on each commit. This helps t' help debugg'n o' user related issues.

Mak'n Releases

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 immutable. 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

  • th' milestone exists
  • there be at least one closed issue assigned t' th' milestone
  • all assigned issues fer this milestone be closed
  • if it’s a main release, there must be an accompany'n releasenotes file present 'n th' repo at introduction/releasenotes/<major>/<minor>.en.md

Aft a successful run o' th' act'n

  • th' changelog at introduction/changelog/<major>/<minor>/<patch>.<lang>.md be created fer english an' piratish, includ'n miss'n generic upper level files
  • th' CHANGELOG.md be updated
  • th' releasenotes at introduction/releasenotes/<major>/<minor>.en.md be updated, includ'n release version an' release date
  • miss'n generic upper level files fer english an' piratish be created
  • th' version number fer th' <meta generator> be updated
  • th' updated files be committed
  • th' milestone be closed
  • th' repository be tagged wit' th' version number (eg. 1.2.3), th' main version number (eg. 1.2.x) an' th' major version number (eg. 1.x)
  • a new entry 'n th' GitHub release list wit' th' accord'n changelog will be created
  • th' official documentat'n be built an' deployed
  • th' version number fer th' <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)
  • a new milestone fer th' next patch release be created (this can later be renamed t' a main release if necessary)

Scrrrenshots

Sometimes screenshots need t' be redone. This plank explains how t' create th' different screenshots, tools an' sett'ns

Common

Creat'n:

  • Use English translat'n
  • Empty search
  • Remove history checkmarks but leave it on th' plank thats used fer th' screenshot
  • Aft resize o' th' plank into th' required resolut'n, reload th' plank t' have all scrollbars 'n default load'n posit'n

Demo Screenshot

Rrrambl'n:

A meaningful full-screen screenshot o' an interest'n plank.

Th' rrrambl'n should be:

  • timeless: not show'n any dates or often edited rrrambl'n
  • interest'n: show a bunch o' interest'n elements like head'ns, code, etc
  • balanced: no clutter'n wit' overpresent elements or color'n
  • aligned: aligned outlines

Used by:

Plank URL: Screenshot Link

Creat'n:

  • save as images/screenshot.png
  • from original screenshot, scale t' 900 x 600 an' save as images/tn.png

Remarks:

Th' locat'ns be mandatory due t' Hugo’s theme ship builder.

Preview images/screenshot.png:

Screenshot Screenshot

Preview images/tn.png:

tn tn

Hero Image

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:

  • consistent: always use th' same plank fer all devices
  • pleas'n: use a delightful background

Used by:

Plank URL: Hero Image Link

Creat'n:

Preview images/hero.png:

Hero Hero

Shortcode Feature Images

Th' feature images fer th' shorrrtcodes be generated automatically via a Node.js script.

It be located 'n th' repository inside o' th' /tools directory. All follow'n commands need t' be executed from this directory.

T' recreate th' screenshots

  • install Node.js accord'n t' their installat'n guide
  • run npm install
  • run npm run screenshots