Merge pull request #75 from pleonex/feature/doc-workflows

📚  Document workflows

.github/ISSUE_TEMPLATE/feature_design.md

@@ -0,0 +1,80 @@
+---
+name: Design
+about: Design a new component or feature
+title: "[Design] "
+labels: ""
+assignees: ""
+---
+
+## Description
+
+TODO: describe the new feature or product
+
+### User stories
+
+TODO: user stories in "AS A/I WANT/SO THAT" format.
+
+### State of the art
+
+TODO: is there any way to implement or use it with the current state? Is there
+any other production implementing it similar?
+
+## Technology
+
+### Candidate 1
+
+TODO: description, pros/cons and links
+
+## High level components
+
+TODO: diagram
+
+### Component 1
+
+TODO: describe the component, what it does and how it interacts with others
+
+## Deployment
+
+TODO: if it applies for the project, how to deploy this new feature or product
+
+### Installation
+
+TODO: how to install it or get it?
+
+### Upgrade
+
+TODO: how users will upgrade to a new version? migration scripts? support
+side-by-side versions?
+
+### Configuration
+
+TODO: how to configure the new components? what technology to use for
+configuration?
+
+### Monitoring
+
+TODO: is it required to monitor the product running on production (e.g. cloud
+apps)? how?
+
+### Logging
+
+TODO: how to log messages and view them? distributed logging? open telemetry?
+
+## Public API
+
+TODO: class diagram with an overview of the new API.
+
+## Extensibility
+
+TODO: how users (developers) will be able to extend the API to adjust to their
+needs?
+
+## Frontend
+
+### UI
+
+TODO: diagram with the UI design
+
+### Frontend components
+
+TODO: related components and API for the frontend side.

.github/pull_request_template.md

@@ -1,20 +1,22 @@
 TODO: description of the PR work.
 
+This PR closes #
+
+## Quality check list
+
 - [ ] Related code has been tested automatically or manually
 - [ ] Related documentation is updated
 - [ ] I acknowledge I have read and filled this checklist and accept the
       [developer certificate of origin](https://developercertificate.org/)
 
-This PR closes #
-
 ## Acceptance criteria
 
 TODO: list of expectations it has passed from the related issue.
 
-### Follow-up work
+## Follow-up work
 
 TODO: describe any missing or future required work.
 
-### Example
+## Example
 
 TODO: small code-snippet or screenshot of the work

docs/articles/toc.yml

@@ -1,6 +1,7 @@
-- name: ✨ Getting started
-- name: Introduction
+- name: 🏠 Introduction
   href: ../index.md
+
+- name: 📁 Repository setup
 - name: Setup guide
   items:
     - name: Creating a build orchestrator
@@ -21,14 +22,14 @@
   href: ./getting-started/build-script.md
 - name: .NET tips and best-practices
   href: ./getting-started/env-dotnet.md
-#- name: Framework architecture
-#  href: ./getting-started/architecture.md
 
 - name: ♻ Workflows
-- name: 🚧 Pipeline
+- name: Pipeline
   href: ./workflows/pipeline.md
-#- name: Versioning
-#  href: ./workflows/versioning.md
+- name: Git flow
+  href: ./workflows/gitflow.md
+- name: Versioning
+  href: ./workflows/versioning.md
 - name: 🚧 Translation
   href: ./workflows/translation.md
 

docs/articles/workflows/gitflow.md

@@ -0,0 +1,137 @@
+# Git flow
+
+Following git flow style, there are three types of branches: main, feature and
+release branches.
+
+```mermaid
+---
+title: "Git flow"
+config:
+  theme: base
+  gitGraph:
+    showCommitLabel: false
+    mainBranchOrder: 2
+---
+
+gitGraph LR:
+  commit tag: "Preview"
+
+  # Feature into main
+  branch feature/name order: 1
+  commit tag: "Dev"
+  commit tag: "Dev"
+  checkout main
+  merge feature/name tag: "Preview"
+
+  # Create release branch (LTS)
+  branch release/3.2 order: 3
+  commit tag: "Preview"
+
+  # Hotfix after manual test failures
+  branch feature/hotfix order: 4
+  commit tag: "Dev"
+  commit tag: "Dev"
+  checkout release/3.2
+  merge feature/hotfix tag: "v3.2.1001 - Production"
+
+  # In parallel, new features to main
+  checkout main
+  branch feature/name2 order: 0
+  commit tag: "Dev"
+  commit tag: "Dev"
+  checkout main
+  merge feature/name2 tag: "Preview"
+
+  # Merge release branch
+  checkout main
+  merge release/3.2  tag: "Preview"
+
+  # Patch on LTS
+  checkout release/3.2
+  branch feature/hotfix2 order: 5
+  commit tag: "Dev"
+  checkout release/3.2
+  merge feature/hotfix2 tag: "v3.2.1002 - Production"
+
+  # Merge hotfix to main as cherry-picks from now on
+  checkout main
+  commit type: HIGHLIGHT tag: "cherry-pick hotfix2 - Preview"
+```
+
+## Main branch
+
+Also known as `develop`, it's the current development branch with latest
+features and fixes.
+
+This branch should be **protected** so no direct pushes are allowed. Changes
+should come via _pull requests_ from feature branches.
+
+Pushing in this branch new comments will trigger a new _preview_ build type.
+This means that artifacts are deployed to the preview / staging feeds. This will
+only happens when a pull request is merged.
+
+> [!NOTE]  
+> If you are working on a small, personal project alone, it should be fine not
+> using pull requests and pushing directly.
+
+## Feature branches
+
+Development branches for small features and bug fixes.
+
+They are prefixed with `feature/` for all type of work (including bug fixes).
+This simplifies the configuration of tools (like GitVersion) and gives
+consistency in the branching schema.
+
+Building locally or in pull requests creates a _development_ build. No artifacts
+are deployed, but they should be accessible to download and test from CI output.
+
+> [!TIP]  
+> Merging pull requests with the _squash_ strategy could be a good idea as it
+> keeps a clean git history. The only exception is the first merge from the
+> release branch into the main.
+
+## Release branches
+
+Branches that help with the release and support process of a product release. In
+a release branch you can stabilize the release without stopping development in
+the _main_ branch of new features that won't go into that release.
+
+They are prefixed with `release/` followed by the major and minor version
+numbers.
+
+Pushing changes into a release branch should happen only via pull requests that
+are carefully reviewed. A new commit will trigger a new _preview_ build.
+
+Once the release is ready, stakeholders would signs-off / approve the release
+and its quality assurance results. This approval is transformed into a new git
+tag to the latest commit. Pushing a tag will trigger a new _production build_.
+
+After the release is out, a _release_ (also known as _support_) branch can be
+used to work on regular patch release like for _long-term support (LTS)_
+versions. Otherwise, remove them as they do not offer any advantage. You can
+always re-create it from the latest git tag.
+
+> [!NOTE]  
+> In a small, personal projects you most likely won't need these branches. Just
+> tag directly `main`, for instance by creating a _GitHub release_. You can
+> always check-out a _tagged commit_, branch and create a _patch release_ from
+> there if needed.
+
+## Epic branches
+
+Special type of a development branch. It helps to implement large features that
+could affect the development of other current features.
+
+It acts as a **temporary** parallel branch to `main`. Feature branches related
+to the feature are merged into the epic. Once the feature is stable enough, the
+epic is merged into the `main` branch as it were a _big_ feature branch.
+
+Try to minimize the usage of _epic_ branches to prevent huge merge conflicts
+later.
+
+> [!NOTE]  
+> This schema does not use a `master` branch as the original
+> [_git flow_](https://nvie.com/posts/a-successful-git-branching-model/)
+> proposed. This branch has not much use. It's possible to get the latest stable
+> version by listing _git tags_. Not having the branch prevents typical issues
+> with the merges and conflicts.