nishiki/hugo-theme-relearn
1
0
Fork 0
mirror of https://github.com/McShelby/hugo-theme-relearn.git synced 2024-11-23 07:47:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: add contribution and release guidelines

Browse source
This commit is contained in:
Sören Weber 2023-01-28 14:48:08 +01:00
parent df66b6fade
commit f183d83e15
No known key found for this signature in database
GPG key ID: BEC6D55545451B6D
7 changed files with 187 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
.github/contributing.md vendored
View file

@ -1,28 +0,0 @@
# Guidelines
## For Development
- help us putting your code into production by opening a meaningful issue
- stay simple for the user by focusing on the mantra "convention over configuration"
- at installation the site should work reasonable without (m)any configuration
- stay close to the Hugo way
- don't use npm or any preprocessing, our contributors may not be front-end developers
- document new features in exampleSite
- don't break existing features if you don't have to
- remove reported issue from the browser's console
- be compatible to IE11, at least for main functionality, for Javascript this means:
- test in IE11
- check caniuse.com
- don't use arrow functions
- don't use template literals
- don't use other fancy new ES5/6 stuff
## For Release
- create releases following [semver policy](https://semver.org/)
- we are using GitHub actions to create new releases
- a release is based on a milestone named like the release itself - just the version number, eg: 1.1.0
- remember that there have to be at least one closed issue assigned to the milestone
- the release action only runs successfully if all assigned issues for this milestone are closed
- the milestone itself will be closed during execution of the action
- a once released milestone can not be released again

2
README.md
View file

@ -55,7 +55,7 @@ See the [What's New](https://mcshelby.github.io/hugo-theme-relearn/basics/migrat
## Contribution
You are most welcome to contribute bugfixes or even new features to the source code. Please visit the [contribution guidelines](https://github.com/McShelby/hugo-theme-relearn/blob/main/.github/contributing.md) first.
You are most welcome to contribute bugfixes or even new features to the source code. Please visit the [contribution guidelines](https://mcshelby.github.io/hugo-theme-relearn/dev/contributing) first.
## License

2
exampleSite/content/_index.en.md
View file

@ -54,7 +54,7 @@ To get support, feel free to open a new [discussion topic](https://github.com/Mc
Feel free to update this documentation by just clicking the {{% button style="transparent" icon="pen" %}}{{% /button %}} button displayed on top right of each page. Your changes will be deployed automatically once they were reviewed.
You are most welcome to contribute bugfixes or even new features to the source code by making pull requests to the [official repository](https://github.com/McShelby/hugo-theme-relearn) via GitHub. Please visit the [contribution guidelines](https://github.com/McShelby/hugo-theme-relearn/blob/main/.github/contributing.md) first.
You are most welcome to contribute bugfixes or even new features to the source code by making pull requests to the [official repository](https://github.com/McShelby/hugo-theme-relearn) via GitHub. Please visit the [contribution guidelines]({{%relref "dev/contributing" %}}) first.
## License

55
exampleSite/content/dev/contributing/_index.en.md Normal file
View file

@ -0,0 +1,55 @@
+++
description = "What to know if you want to contribute"
title = "Contributing"
+++
## Code Quality
A new release can happen at any time from the `main` branch of the [GitHub project](https://github.com/McShelby/hugo-theme-relearn) without further accknowledgment. This makes it necessary that, every pushed set of changesets into the `main` branch **must** be self-contained and correct, resulting in a releasable version.
Stay simple for the user by focusing on the mantra "convention over configuration".
At installation the site should work reasonable without (m)any configuration.
Stay close to the Hugo way.
Don't use npm or any preprocessing, our contributors may not be front-end developers.
Document new features in the exampleSite. This also contains entries to the [What's new]({{% relref "basics/migration" %}}) page.
Don't break existing features if you don't have to.
Remove reported issue from the browser's console.
Check for unnecessary whitespace and correct indention of your resulting HTML.
Be compatible to IE11, at least for main functionality, this means:
- test in IE11
- check caniuse.com
- don't use JavaScript arrow functions
- don't use JavaScript template literals
- don't use other fancy JavaScript ES5/6 stuff
## Conventional Commits
Write commit messages in the [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) format.
Following is an impomplete list of some of the used conventional commit types. Be creative.
| Common | Feature | Structure | Shortcodes |
|------------|------------|-----------------|-------------|
| build | a11y | favicon | attachments |
| browser | archetypes | search | badge |
| chore | alias | menu | button |
| docs | generator | history | children |
| shortcodes | i18n | scrollbar | expand |
| theme | mobile | nav | icon |
| | print | toc | include |
| | rss | clipboard | math |
| | variant | syntaxhighlight | mermaid |
| | | boxes | notice |
| | | | piratify |
| | | | siteparam |
| | | | swagger |
| | | | tabs |

5
exampleSite/content/dev/contributing/_index.pir.md Normal file
View file

@ -0,0 +1,5 @@
+++
description = "What to know if you want to contribute"
title = "Contributing"
+++
{{< piratify >}}

120
exampleSite/content/dev/maintaining/_index.en.md Normal file
View file

@ -0,0 +1,120 @@
+++
description = "What to know as a maintainer"
title = "Issue and Release Management"
+++
## Semver
This project tries to follow the [semver policy](https://semver.org/) - although not followed 100% in the past.
Usually an entry of {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} on the [What's new]({{% relref "basics/migration" %}}) page causes a new major release number.
All other entries on the [What's new]({{% relref "basics/migration" %}}) page will increase the minor release number.
Releases resulting in a new major or minor number are called main release.
Releases containing bugixes only, are only increasing the patch release number. Those releases don't result in announcements on the [What's new]({{% relref "basics/migration" %}}) page.
Entries on the [What's new]({{% relref "basics/migration" %}}) page are checked and enforced during the `version-release` GitHub Action.
## Managing Issues
Issues are categorized and managed by assigning [labels](#labels) to it.
Once working on an issue, assign it to a fitting maintainer.
When done, close the ticket. Once an issue is closed, it needs to be assigned to next release milestone.
## Managing Pull Requests
If a PR is merged and closed it needs an accompanied issue assigned to. If there is no issue for a PR, the maintainer needs to create one.
You can assign multiple PRs to one issue as long as they belong together.
Usually set the same labels and milestone for the PR as for the accompanied issue.
## Labels
### Kind
An issue that results in changesets must have exactly one of the following labels. This needs to be assigned latest before release.
| Label | Description | Changelog section |
|----------------------------------------------------------|--------------------------------------------|-------------------|
| {{% badge color="#5498d8" %}}documentation{{% /badge %}} | Improvements or additions to documentation | - |
| {{% badge color="#99d856" %}}discussion{{% /badge %}} | This issue was converted to a discussion | - |
| {{% badge color="#d8d104" %}}task{{% /badge %}} | Maintainence work | Maintenance |
| {{% badge color="#d8ae04" %}}feature{{% /badge %}} | New feature or request | Features |
| {{% badge color="#d88704" %}}bug{{% /badge %}} | Something isn't working | Fixes |
### Impact
If the issue would cause a new main release due to [semver semantics](#semver) it needs one of the according labels and the matching badge on the [What's new]({{% relref "basics/migration" %}}) page.
| Label | Description |
|-----------------------------------------------------|---------------------------------------------------------|
| {{% badge color="#d73a4a" %}}change{{% /badge %}} | Introduces changes with existing installations |
| {{% badge color="#d73a4a" %}}breaking{{% /badge %}} | Introduces breaking changes with existing installations |
### Declination
If an issue does not result in changesets but is closed anyways, it must have exactly one of the following labels.
| Label | Description |
|-------------------------------------------------------|-------------------------------------------
| {{% badge color="#9fa2a5" %}}duplicate{{% /badge %}} | This issue or pull request already exists |
| {{% badge color="#9fa2a5" %}}invalid{{% /badge %}} | This doesn't seem right |
| {{% badge color="#9fa2a5" %}}unresolved{{% /badge %}} | No progress on this issue |
| {{% badge color="#9fa2a5" %}}wontfix{{% /badge %}} | This will not be worked on |
### Halt
You can assign one further label out of the following list to signal readers that development on an open issue is currently halted for different reasons.
| Label | Description |
|----------------------------------------------------------|---------------------------------------------------------|
| {{% badge color="#998f6b" %}}blocked{{% /badge %}} | Depends on other issue to be fixed first |
| {{% badge color="#998f6b" %}}idea{{% /badge %}} | A valuable idea that's currently not worked on |
| {{% badge color="#998f6b" %}}undecided{{% /badge %}} | No decission was made yet |
| {{% badge color="#6426ff" %}}helpwanted{{% /badge %}} | Great idea, send in a PR |
| {{% badge color="#6426ff" %}}needsfeedback{{% /badge %}} | Further information is needed |
### 3rd-Party
If the issue is not caused by a programming error in the themes own code, you can label the causing program or library.
| Label | Description |
|----------------------------------------------------|-------------------------------------------------------------|
| {{% badge color="#e550a7" %}}browser{{% /badge %}} | This is a topic related to the browser but not the theme |
| {{% badge color="#e550a7" %}}hugo{{% /badge %}} | This is a topic related to Hugo itself but not the theme |
| {{% badge color="#e550a7" %}}mermaid{{% /badge %}} | This is a topic related to Mermaid itself but not the theme |
## Making Releases
A release is based on a milestone named like the release itself - just the version number, eg: `1.2.3`. It's in the maintainers responsiblity to check [semver semantics](#semver) of the milestone's name prior to release and change it if necessary.
Making releases is automated by the `version-release` GitHub Action. It requires the version number of the milestone that should be released. The release will be created from the `main` branch of the repository.
During execution of the action a few things are checked. If a check fails the action fails, resulting in no new release. You can correct the errors afterwards and rerun the action.
The following checks will be enforced
- the milestone exists
- there is at least one closed issue assigned to the milestone
- all assigned issues for this milestone are closed
- the milestone is not previously released
- if it's a main release, there must be a new `<major>.<minor>` at the beginning of the [What's new]({{% relref "basics/migration" %}}) page
- if it's a patch release, there must be the `<major>.<minor>` from the previous release at the beginning of the [What's new]({{% relref "basics/migration" %}}) page
After a successful run of the action
- the [History](https://mcshelby.github.io/hugo-theme-relearn/basics/history/index.html) page is updated
- the [What's new](https://mcshelby.github.io/hugo-theme-relearn/basics/migration/index.html) page is updated
- the version number for the `<meta generator>` is updated
- the updated files are commited
- the milestone is closed
- the repository is tagged with the version number
- a new entry in the [GitHub release list](https://github.com/McShelby/hugo-theme-relearn/releases) with the according changelog will be created
- the [official documentation](https://mcshelby.github.io/hugo-theme-relearn/index.html) is built and deployed
- the version number for the `<meta generator>` is updated to a temporary and commited (this helps to determine if users are running directly on the main branch or are using releases)
- a new milestone for the next patch release is created (this can later be renamed to a main release if necessary)

5
exampleSite/content/dev/maintaining/_index.pir.md Normal file
View file

@ -0,0 +1,5 @@
+++
description = "What to know as a maintainer"
title = "Issue and Release Management"
+++
{{< piratify >}}