From 84e2767eb191987df41fe0f9b7680005f37c7502 Mon Sep 17 00:00:00 2001 From: dd84ai Date: Sun, 10 Dec 2023 03:44:45 +0100 Subject: [PATCH] refactor: remaining documentation in folder --- .../workflows/{changelog.yml => validate.yml} | 0 README.md | 12 ++++-- docs/development/algos.md | 39 +++-------------- docs/development/code_architecture.md | 13 +----- docs/intro/1_reasoning.md | 22 ---------- docs/intro/2_installation.md | 42 ------------------- 6 files changed, 16 insertions(+), 112 deletions(-) rename .github/workflows/{changelog.yml => validate.yml} (100%) delete mode 100644 docs/intro/1_reasoning.md delete mode 100644 docs/intro/2_installation.md diff --git a/.github/workflows/changelog.yml b/.github/workflows/validate.yml similarity index 100% rename from .github/workflows/changelog.yml rename to .github/workflows/validate.yml diff --git a/README.md b/README.md index a8862d9..4342788 100644 --- a/README.md +++ b/README.md @@ -6,16 +6,16 @@ **Communicating through git professionally** -autogit is a CLI tool to validate submitted commits according to [git conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) standard. the tool allows to generate changelogs for releases in different formats. When you generate changelogs and see quick feedback of an end result, it promotes you to write commits better. +autogit is a CLI tool to validate submitted commits according to [git conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) standard. the tool allows to generate changelogs for releases in different formats. With ability to see quickly how your changelog looks like, it motivates you to write more meaningful commits -as a result of a tool work, you communicate your developer work better to other developers and have more professional looking repository. +as a result of a tool work, you have decreased toll on release documentation writing and you communicate your developer work better to other developers/users and have more professional looking repository in terms of commits, tags, versions, releases and changelogs. # Features - hooks to git-hooks and works to validate your git commits to [git conventional commits]((https://www.conventionalcommits.org/en/v1.0.0/)) standard for any git tool. - has extra possible validating rules to configure, like having minimum 3 words in a subject of a commit. - `autogit hook activate --global`(flag to turn it on for all repos) -- suggests next [semantic version](https://semver.org/) with `autogit semver` +- suggests next [semantic version](https://semver.org/) for your product release with `autogit semver` - has options to sugest next version as alpha, beta, prerelease version with build meta data. - generates changelogs with `autogit changelog` command - currently supports markdown and bbcode formats @@ -24,7 +24,11 @@ as a result of a tool work, you communicate your developer work better to other - initialize settings for more customization with `autogit init` inside git repo - uncomment and override desired settings - find out more commands and options with `autogit [any set of sub commands] --help` -- CI friendly, not requires any dependencies for its usage for everything (inbuilt git-go to access git information) +- CI friendly binary file, not requires any dependencies for its usage for everything + - see [CI example](.github/workflows/validate.yml) + - compliled for linux/windows/macos and amd64/arm64/386/arm + - Contains inbuilt git. Not requiring git to be installed for its functionality + # Getting started diff --git a/docs/development/algos.md b/docs/development/algos.md index 004ab5e..cf17ffc 100644 --- a/docs/development/algos.md +++ b/docs/development/algos.md @@ -5,14 +5,7 @@ You try to write git commit -m "feat: add rendering in format format" your githook is activated and tries to parse your commit name accroding to git conventional commits standard. If unable, it will give you error and prevent commit - - - - - - - - 
+```mermaid
 flowchart TD
   GitCommit[attempt to fixate commit like
   git commit -m 'feat: add md rendering'
@@ -29,22 +22,13 @@ flowchart TD
   CheckOptionalValidationRulesIfEnabled --> WhenAppliedRules[when applied rules]
   WhenAppliedRules --> IfCommit[if it was commit,\nthen fixate if passed rules,\nor cancel fixation]
   WhenAppliedRules --> IfChangelog[if it was changelog validation\nthen report no errors and exit code 0\nfor pipeline checks]
-
- - +``` ## scenario #2 - changelog / Your wish to see changelog of additions you made, what are new features, what are fixes. For user view You wish to have changelog auto generated. - - - - - - - - 
+```mermaid
 flowchart TD
     RequestingChangelog[Requesting changelog]
     RequestingChangelog --> ChangelogFromLatestCommitToPreviousTagVersion
@@ -71,9 +55,7 @@ flowchart TD
     RenderChangelogMarkdown[Render in markdown\n--implemented--]
     RenderChangelogRst[Render in rst\n--not implemented--]
     RenderChangelogHtml[Render in html\n--not implemented--]
-
- - +``` ### example of rendered changelog @@ -91,14 +73,7 @@ Program checks if u made no commits, or only refactoring and styling. more detailed algorithm, accounting also prerelease version calculations: - - - - - - - - 
+```mermaid
 flowchart TD
   RequestNextSemanticVersioning[Request next semantic versioning]
   RequestNextSemanticVersioning --> FindCommits[Find commits\nfrom HEAD^1 to previous stable semantic version like v0.3.0]
@@ -122,6 +97,4 @@ flowchart TD
   CalculatedMainVersion ----> AddBuildMetaData[Add build meta data\nas +$BuildMetaData\nto the end of version]
   CombineIntoTotalPrereleaseVersion --> OutputFinalSemanticVersion
   AddBuildMetaData --> OutputFinalSemanticVersion[Render Final Semantic Version]
-
- - +``` diff --git a/docs/development/code_architecture.md b/docs/development/code_architecture.md index 48e4206..7dd7d51 100644 --- a/docs/development/code_architecture.md +++ b/docs/development/code_architecture.md @@ -12,14 +12,7 @@ ## Diagram - - - - - - - - 
+```mermaid
 flowchart TD
   UI[Interface-CLI\nUser interface via Cobra CLI third party lib]
   UI --> Actions[Actions\nreusable actions without\nattachements to UI details]
@@ -31,9 +24,7 @@ flowchart TD
   SemanticGit --> SemVer[SemVer\nimplements original Semantic Version\naccording to SemVer2.0.0 standard\nImplemented in current repo]
   SemanticGit --> Git[Git\ngit wrapper to simple interface\nfor current repository logic\nimplemented in current repo]
   Git --> GitGo[Git-Go\nEngine under the hood for\nGit repository operations\nImplemented by third party]
-
- - +``` ## Support promises: diff --git a/docs/intro/1_reasoning.md b/docs/intro/1_reasoning.md deleted file mode 100644 index 5a4e70a..0000000 --- a/docs/intro/1_reasoning.md +++ /dev/null @@ -1,22 +0,0 @@ -# Intro - Reasoning - -So in a nutshell, it takes away complexity of using git conventional commits and semantic versioning. You are auto guided and auto corrected how correctly to perform it xD -u only need correctly writing meaning/subject/description to your commits 🙂 but since u see what is rendered to users, you quickly learn how to write it better -Plus it was made in CI friendly way - -why semantic versioning is important, to read here https://semver.org/ -well, about git conventional commits is here: https://www.conventionalcommits.org/en/v1.0.0/ - -as an example, all my releases of darktool were made with similar automatation. -Changelogs and versions https://github.com/darklab8/darklab_freelancer_darktool/releases - -## 🎯 Goals - -- CI friendly tool for automatic following of [Git Conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) rules (standard for more descriptive commits) -- The tool generates automatically changelogs of new features and bug fixes for your product releases -- and also calculates next [semantic version](https://semver.org/) your next product release should be having - -Essentially tool... To decrease toll on release documentation writing, and to start writing more descriptive commits \ -It will help to make your repository looking like more professional in terms of commits, tags, versions, releases and changelogs. \ -With ability to see quickly how your changelog looks like, it will motivate you to write more meaningful commits - diff --git a/docs/intro/2_installation.md b/docs/intro/2_installation.md deleted file mode 100644 index b06e883..0000000 --- a/docs/intro/2_installation.md +++ /dev/null @@ -1,42 +0,0 @@ -# Installation - -## 🚀 Short opinionated installation - -2) `autogit semver` to verify installation and get next expected semantic version -3) (Optional) config init - - * `autogit init` to create `autogit.yml` config locally in repo. - * `autogit init --global` to make user global settings file fallback - * if u will do nothing, program will just fallback to using config from memory -4) `autogit hook activate` to turn validation commit hooks on - - * `autogit hook activate --global` will turn it on globally for all repos - * `autogit hook deactivate` (also with possible flag `--global`) can serve to deactivate this functionality - -## ✈️ Detailed installation - -1. [download latest stable release](https://github.com/darklab8/darklab_autogit/releases) and put to env PATH searchable range - -- Linux: - - - Check your PATH bin serachable locations with `echo "$PATH"` and put into any of them or add new location, change settings to allow it being executable with `chmod` - - Recomendation to put into `/usr/local/bin` - - Linux ubuntu one liner: `curl -o /usr/local/bin/autogit https://github.com/darklab8/darklab_autogit/releases/download/v2.1.0/autogit-linux-amd64 && chmod 777 /usr/local/bin/autogit` -- Windows: - - - Check your PATH bin locations with `echo %PATH%` and put binary file any of them or add to new one, be sure to rename from like `autogit-windows-amd64.exe` to `autogit.exe` - - If u use `Git Bash`, recommendation to put into `~/bin` for usage in Git Bash only, or into `C:\Program Files\Git\cmd` for working in any terminal - - U can add to any other PATH bin searchable locations or add a new one -- MacOS - - - (To be written where to put) - -2. (Optional) init autogit.yml with `autogit init` command in the root of repository. change REPOSITORY_OWNER and REPOSITORY_NAME to yours - 1. Or init global one, or don't init at all (see 3d step of short opinionated instructioon) -3. run `autogit hook activate` to create `.git-hook` folder and enabling it in your git config for automated commit validation on pre-commit hook - 1. Or activate globally with flag `--global` - 2. `deactivate with `autogit hook deactivate`, using `--global` flag if necessary as well. - -P.S. Current repository runs on configured autogit as well - -