[Docs] Add a PlantUML activity diagram of header fixing mechanism (#41)

.github/workflows/docs-plantuml-check.yaml

@@ -0,0 +1,42 @@
+# Licensed to Apache Software Foundation (ASF) under one or more contributor
+# license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright
+# ownership. Apache Software Foundation (ASF) licenses this file to you under
+# the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+name: PlantUML SVG Diagrams
+
+on:
+  pull_request:
+    paths:
+      - 'docs/*.plantuml'
+      - 'docs/*.svg'
+  push:
+    branches:
+      - main
+
+jobs:
+  check-plantuml-svg-diagram-consistency:
+    name: Checking consistency of diagram files
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions/setup-java@v2
+        with:
+          distribution: 'adopt'
+          java-version: '11'
+
+      - run: make verify-docs

.gitignore

@@ -20,3 +20,4 @@ bin/
 assets/assets.gen.go
 .DS_Store
 coverage.txt
+plantuml.jar

.licenserc.yaml

@@ -73,6 +73,7 @@ header: # `header` section is configurations for source codes license header.
     - '**/assets/lcs-templates/**'
     - '**/assets/languages.yaml'
     - '**/assets/assets.gen.go'
+    - 'docs/**.svg'
 
   comment: on-failure # on what condition license-eye will comment on the pull request, `on-failure`, `always`, `never`.
 

Makefile

@@ -29,6 +29,8 @@ GO_TEST = $(GO) test
 GO_LINT = $(GO_PATH)/bin/golangci-lint
 GO_BUILD_LDFLAGS = -X github.com/apache/skywalking-eyes/$(PROJECT)/commands.version=$(VERSION)
 
+PLANTUML_VERSION = 1.2021.9
+
 PLATFORMS := windows linux darwin
 os = $(word 1, $@)
 ARCH = amd64
@@ -77,7 +79,7 @@ clean:
 	-rm -rf "$(RELEASE_SRC)"*
 
 .PHONY: verify
-verify: clean license lint test
+verify: clean license lint test verify-docs
 
 release-src: clean
 	-tar -zcvf $(RELEASE_SRC).tgz \
@@ -105,3 +107,17 @@ release: verify release-src release-bin
 	shasum -a 512 $(RELEASE_SRC).tgz > $(RELEASE_SRC).tgz.sha512
 	gpg --batch --yes --armor --detach-sig $(RELEASE_BIN).tgz
 	shasum -a 512 $(RELEASE_BIN).tgz > $(RELEASE_BIN).tgz.sha512
+
+.PHONY: docs-gen
+docs-gen:
+	-if [ ! -f "plantuml.jar" ]; then curl -sL -o plantuml.jar https://repo1.maven.org/maven2/net/sourceforge/plantuml/plantuml/$(PLANTUML_VERSION)/plantuml-$(PLANTUML_VERSION).jar; fi;
+	-java -jar plantuml.jar -tsvg -nometadata "docs/*.plantuml"
+
+.PHONY: verify-docs
+verify-docs: docs-gen
+	@if [ ! -z "`git status -s docs`" ]; then \
+		echo "Following diagram files are not consistent with CI:"; \
+		git status -s docs; \
+		git diff --color --word-diff --exit-code docs; \
+		exit 1; \
+	fi

README.md

@@ -242,6 +242,11 @@ The `header check` command theoretically supports all kinds of file types, while
   3. The leading characters of the middle lines of a block comment.
   4. The leading characters of the ending line of a block comment.
 
+## Technical Documentation
+
+- There is an [activity diagram](./docs/header_fix_logic.svg) explaining the implemented license header 
+  fixing mechanism in-depth. The diagram's source file can be found [here](./docs/header_fix_logic.plantuml).
+
 ## Contribution
 
 - If you find any file type should be supported by the aforementioned configurations, but it's not listed there, feel free to [open a pull request](https://github.com/apache/skywalking-eyes/pulls) to add the configuration into the two files.

docs/header_fix_logic.plantuml

@@ -0,0 +1,63 @@
+@startuml
+
+' Licensed to Apache Software Foundation (ASF) under one or more contributor
+' license agreements. See the NOTICE file distributed with
+' this work for additional information regarding copyright
+' ownership. Apache Software Foundation (ASF) licenses this file to you under
+' the Apache License, Version 2.0 (the "License"); you may
+' not use this file except in compliance with the License.
+' You may obtain a copy of the License at
+'
+'     http://www.apache.org/licenses/LICENSE-2.0
+'
+' Unless required by applicable law or agreed to in writing,
+' software distributed under the License is distributed on an
+' "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+' KIND, either express or implied.  See the License for the
+' specific language governing permissions and limitations
+' under the License.
+
+' the following line cares about avoiding the need of graphviz dependency by PlantUML (in CI))
+!pragma layout smetana
+
+title "Apache/Skywalking-Eyes: Header fix process activity diagram"
+footer apache/skywalking-eyes
+
+(*) --> "Start of 'header fix'. Processing files\nwithout proper headers file by file." as startNode
+
+partition singleFileProcess {
+startNode --> "Start of single file process" as startFileNode
+
+if "<i>comment_style_id</i> is set for this language/file type" then
+    -->[yes] "Try to fix license header of file"
+
+    if <i>After</i> is set in CommentStyle then
+        -->[yes] Look for <i>After</i>-pattern in file content
+
+        if pattern is found then
+            ------->[yes] "fileContent := contentPart1 + licenseHeader + contentPart2"
+            ---> "End of fixing license header for this file" as endFileProcessingNode
+        else
+            --->[no] "<i>After</i>-pattern not found"
+
+            if "<i>ensure_after</i> is set" then
+                ---->[yes] "fileContent := <i>ensureAfter</i> + licenseHeader + <i>ensureBefore</i> + content"
+                ---> endFileProcessingNode
+            else
+                --->[no] "fileContent := licenseHeader + content" as defaultHeaderFix
+            endif
+
+        endif
+    else
+        -->[no] defaultHeaderFix
+        ---> endFileProcessingNode
+    endif
+else
+    ---->[no] endFileProcessingNode
+endif
+}
+
+endFileProcessingNode --> "End of 'header fix' process" as endNode
+endNode --> (*)
+
+@enduml