From f183d83e1500da02bdcf880f171b75026becbdfa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6ren=20Weber?= Date: Sat, 28 Jan 2023 14:48:08 +0100 Subject: [PATCH] docs: add contribution and release guidelines --- .github/contributing.md | 28 ---- README.md | 2 +- exampleSite/content/_index.en.md | 2 +- .../content/dev/contributing/_index.en.md | 55 ++++++++ .../content/dev/contributing/_index.pir.md | 5 + .../content/dev/maintaining/_index.en.md | 120 ++++++++++++++++++ .../content/dev/maintaining/_index.pir.md | 5 + 7 files changed, 187 insertions(+), 30 deletions(-) delete mode 100644 .github/contributing.md create mode 100644 exampleSite/content/dev/contributing/_index.en.md create mode 100644 exampleSite/content/dev/contributing/_index.pir.md create mode 100644 exampleSite/content/dev/maintaining/_index.en.md create mode 100644 exampleSite/content/dev/maintaining/_index.pir.md diff --git a/.github/contributing.md b/.github/contributing.md deleted file mode 100644 index 0bcbe39e08..0000000000 --- a/.github/contributing.md +++ /dev/null @@ -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 diff --git a/README.md b/README.md index d8af93a0e2..5edad23267 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/exampleSite/content/_index.en.md b/exampleSite/content/_index.en.md index 41335f3d74..3edf463bb8 100644 --- a/exampleSite/content/_index.en.md +++ b/exampleSite/content/_index.en.md @@ -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 diff --git a/exampleSite/content/dev/contributing/_index.en.md b/exampleSite/content/dev/contributing/_index.en.md new file mode 100644 index 0000000000..db9a767bf0 --- /dev/null +++ b/exampleSite/content/dev/contributing/_index.en.md @@ -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 | diff --git a/exampleSite/content/dev/contributing/_index.pir.md b/exampleSite/content/dev/contributing/_index.pir.md new file mode 100644 index 0000000000..8f8518feab --- /dev/null +++ b/exampleSite/content/dev/contributing/_index.pir.md @@ -0,0 +1,5 @@ ++++ +description = "What to know if you want to contribute" +title = "Contributing" ++++ +{{< piratify >}} \ No newline at end of file diff --git a/exampleSite/content/dev/maintaining/_index.en.md b/exampleSite/content/dev/maintaining/_index.en.md new file mode 100644 index 0000000000..e56cab56f4 --- /dev/null +++ b/exampleSite/content/dev/maintaining/_index.en.md @@ -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 `.` at the beginning of the [What's new]({{% relref "basics/migration" %}}) page +- if it's a patch release, there must be the `.` 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 `` 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 `` 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) diff --git a/exampleSite/content/dev/maintaining/_index.pir.md b/exampleSite/content/dev/maintaining/_index.pir.md new file mode 100644 index 0000000000..05bab301f0 --- /dev/null +++ b/exampleSite/content/dev/maintaining/_index.pir.md @@ -0,0 +1,5 @@ ++++ +description = "What to know as a maintainer" +title = "Issue and Release Management" ++++ +{{< piratify >}} \ No newline at end of file