diff --git a/.github/workflows/docs-plantuml-check.yaml b/.github/workflows/docs-plantuml-check.yaml new file mode 100644 index 0000000..3615529 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.gitignore b/.gitignore index faaafa1..8d0e816 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,4 @@ bin/ assets/assets.gen.go .DS_Store coverage.txt +plantuml.jar \ No newline at end of file diff --git a/.licenserc.yaml b/.licenserc.yaml index af8bc1c..611cb75 100644 --- a/.licenserc.yaml +++ b/.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`. diff --git a/Makefile b/Makefile index 918d685..b8468b1 100644 --- a/Makefile +++ b/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 \ No newline at end of file diff --git a/README.md b/README.md index fd00bb4..b457c42 100644 --- a/README.md +++ b/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. diff --git a/docs/header_fix_logic.plantuml b/docs/header_fix_logic.plantuml new file mode 100644 index 0000000..98cdb90 --- /dev/null +++ b/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 "comment_style_id is set for this language/file type" then + -->[yes] "Try to fix license header of file" + + if After is set in CommentStyle then + -->[yes] Look for After-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] "After-pattern not found" + + if "ensure_after is set" then + ---->[yes] "fileContent := ensureAfter + licenseHeader + ensureBefore + 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 \ No newline at end of file diff --git a/docs/header_fix_logic.svg b/docs/header_fix_logic.svg new file mode 100644 index 0000000..7a718a7 --- /dev/null +++ b/docs/header_fix_logic.svg @@ -0,0 +1,2 @@ +Apache/Skywalking-Eyes: Header fix process activity diagramsingleFileProcessStart of 'header fix'. Processing fileswithout proper headers file by file.End of 'header fix' processStart of single file processTry to fix license header of fileLook forAfter-pattern in file contentfileContent := contentPart1 + licenseHeader + contentPart2End of fixing license header for this fileAfter-pattern not foundfileContent :=ensureAfter+ licenseHeader +ensureBefore+ contentfileContent := licenseHeader + contentcomment_style_idis set for this language/file typeyesAfteris set in CommentStyleyespattern is foundyesnoensure_afteris setyesnononoapache/skywalking-eyes \ No newline at end of file