diff --git a/doc/docs/dev-guide/README.md b/doc/docs/dev-guide/README.md index f143fa86..f7434914 100644 --- a/doc/docs/dev-guide/README.md +++ b/doc/docs/dev-guide/README.md @@ -8,14 +8,20 @@ The LPVS Developer Guide provides documentation for developers and contributors. You can jump directly to the pages listed below, or use the *next* and *previous* buttons in the navigation bar at the top of the page to move through the documentation in order. +- [Architecture] - [Contributing guide] +- [Coding style] - [Testing policy] - [Code review requirements] - [API reference] - [Integration guide] +- [FAQ] +[Architecture]: architecture.md [Contributing guide]: contributing.md +[Coding style]: coding-style.md [Testing policy]: testing-policy.md [Code review requirements]: code-review-requirements.md [API reference]: api.md [Integration guide]: integration.md +[FAQ]: faq.md diff --git a/doc/docs/dev-guide/architecture.md b/doc/docs/dev-guide/architecture.md new file mode 100644 index 00000000..74c29dd1 --- /dev/null +++ b/doc/docs/dev-guide/architecture.md @@ -0,0 +1,7 @@ +# Architecture + +How LPVS interacts with other entities. + +--- + +![Architecture](../img/architecture.png) diff --git a/doc/docs/dev-guide/coding-style.md b/doc/docs/dev-guide/coding-style.md new file mode 100644 index 00000000..2e038da4 --- /dev/null +++ b/doc/docs/dev-guide/coding-style.md @@ -0,0 +1,44 @@ +# Coding style + +Explanation of the used coding style. + +--- + +The LPVS project uses the [Google Java Style](https://google.github.io/styleguide/javaguide.html). + +Each Pull Request is checked for compliance with the coding style. If a conflict occurs, a recommendation can be found in the [Check Java Format action](https://github.com/Samsung/LPVS/actions/workflows/java-format-checker.yml). + +Example: + +```bash +diff --git a/src/main/java/com/lpvs/service/LPVSDetectService.java b/src/main/java/com/lpvs/service/LPVSDetectService.java +index 360e21a..880dd2a 100644 +--- a/src/main/java/com/lpvs/service/LPVSDetectService.java ++++ b/src/main/java/com/lpvs/service/LPVSDetectService.java +@@ -84,7 +84,9 @@ public class LPVSDetectService { + this.getInternalQueueByPullRequest(HtmlUtils.htmlEscape(trigger)); + + List scanResult = +- this.runScan(webhookConfig, LPVSDetectService.getPathByPullRequest(webhookConfig)); ++ this.runScan( ++ webhookConfig, ++ LPVSDetectService.getPathByPullRequest(webhookConfig)); + + List> detectedConflicts = + licenseService.findConflicts(webhookConfig, scanResult); +Error: Process completed with exit code 1. +``` + +When preparing a Pull Request, you can run a command that will check and correct the coding style. + +```bash +java -jar google-java-format-1.23.0-all-deps.jar --aosp --skip-javadoc-formatting --skip-reflowing-long-strings --skip-sorting-imports --replace -i $(git ls-files|grep \.java$) +``` + +!!! note + + Download `google-java-format-1.23.0-all-deps.jar` [here](https://github.com/google/google-java-format/releases/download/v1.23.0/google-java-format-1.23.0-all-deps.jar). + +!!! info + + `google-java-format` official repository [link](https://github.com/google/google-java-format). diff --git a/doc/docs/dev-guide/faq.md b/doc/docs/dev-guide/faq.md new file mode 100644 index 00000000..cf77967e --- /dev/null +++ b/doc/docs/dev-guide/faq.md @@ -0,0 +1,184 @@ +# FAQ + +Frequently asked questions and useful information. + +--- + +## Useful utilities + +### Swagger + +* [Swagger](https://swagger.io/) +* [Swagger Editor](https://editor.swagger.io/) + +### PlantUML + +* [PlantUML Language Reference Guide](http://plantuml.com/guide) +* [PlantText - Online Editor](https://www.planttext.com/) + +--- + +## How to sign a release using GPG? + +A good example of a release signature can be found on the [link](https://wiki.debian.org/Creating%20signed%20GitHub%20releases). However, 5 and 6 items are described separately. + +### Creating a key pair + +```bash +gpg --full-generate-key +``` + +During the execution of this command, you will need to enter additional data: + +* Please select what kind of key you want: **1** +* What keysize do you want? (3072): **4096** +* Please specify how long the key should be valid: **0** +* Key is valid for? (0): **0** +* Is this correct? (y/N): **y** +* Real name: **LPVS** +* Email address: **o.kopysov@samsung.com** +* Comment: **Keys for LPVS** + +In this case, the result will be the next + +```bash +gpg (GnuPG) 2.2.4; Copyright (C) 2017 Free Software Foundation, Inc. +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +Please select what kind of key you want: + (1) RSA and RSA (default) + (2) DSA and Elgamal + (3) DSA (sign only) + (4) RSA (sign only) +Your selection? 1 +RSA keys may be between 1024 and 4096 bits long. +What keysize do you want? (3072) 4096 +Requested keysize is 4096 bits +Please specify how long the key should be valid. + 0 = key does not expire + = key expires in n days + w = key expires in n weeks + m = key expires in n months + y = key expires in n years +Key is valid for? (0) 0 +Key does not expire at all +Is this correct? (y/N) y + +GnuPG needs to construct a user ID to identify your key. + +Real name: LPVS +Email address: o.kopysov@samsung.com +Comment: Keys for LPVS +You selected this USER-ID: + "LPVS (Keys for LPVS) " + +Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O +We need to generate a lot of random bytes. It is a good idea to perform +some other action (type on the keyboard, move the mouse, utilize the +disks) during the prime generation; this gives the random number +generator a better chance to gain enough entropy. +We need to generate a lot of random bytes. It is a good idea to perform +some other action (type on the keyboard, move the mouse, utilize the +disks) during the prime generation; this gives the random number +generator a better chance to gain enough entropy. +gpg: key BE13B1D440E813F0 marked as ultimately trusted +gpg: revocation certificate stored as '/home/virtual-pc/.gnupg/openpgp-revocs.d/D3C7C06AC34BDA9A41388E76BE13B1D440E813F0.rev' +public and secret key created and signed. + +pub rsa4096 2021-10-15 [SC] + D3C7C06AC34BDA9A41388E76BE13B1D440E813F0 +uid LPVS (Keys for LPVS) +sub rsa4096 2021-10-15 [E] +``` + +### Create and sign a tag with your created key + +Set your GPG signing key in Git + +```bash +git config --global user.signingkey +``` + +Create and sign the tag + +```bash +git tag -s +``` + +### Sign the release tarball with your created key + +```bash +gpg --armor --detach-sign lpvs-vx.x.x.tar.gz +``` + +!!! note + + If you have multiple keys, you must specify the key that will be used by adding the option `-u ` + +### Extraction a copy of a key pair from local gpg keyring + +```bash +gpg --output lpvs-public.pgp --armor --export o.kopysov@samsung.com +gpg --output lpvs-private.pgp --armor --export-secret-key o.kopysov@samsung.com +``` + +!!! note + + Only the signature file (`lpvs-vx.x.x.tar.gz.asc`) and the public key (`lpvs-public.pgp`) must be loaded as an artifact to release. + +### To sign the release using another computer + +For this need to download the private key (`lpvs-private.pgp`) by the next command: + +```bash +gpg --import lpvs-private.pgp +``` + +--- + +## How to use GPG to verify signed release? + +To perform the verification, you need the following: +* signed file – for example `lpvs-vx.x.x.tar.gz` +* signature file – accompanying file with “.asc” extension (Ex. `lpvs-vx.x.x.tar.gz.asc`) +* public key – for example `lpvs-public.pgp` + +### Import the public key to your keystore + +```bash +gpg --import +``` + +### Verification signed file + +```bash +gpg --verify +``` + +!!! note + + If you have multiple keys, you must specify the key that will be used by adding the option `-u ` + +--- + +## DCO via the command line + +The most popular way to do DCO is to sign off your username and email address in the git command line. + +First, configure your local git install. + +```bash +$ git config --global user.name "John Doe" +$ git config --global user.email johndoe@example.com +``` + +Obviously, you should use your own name and the email address associated with your GitHub user account. + +Now, every time you commit new code in git, just add a signoff statement via the `-s` flag. + +```bash +$ git commit -s -m "This is my commit message" +``` + +That’s it. Git adds your sign-off message in the commit message, and you contribution (commit) is now DCO compliant. diff --git a/doc/docs/img/architecture.png b/doc/docs/img/architecture.png new file mode 100644 index 00000000..d66fec04 Binary files /dev/null and b/doc/docs/img/architecture.png differ diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml index b7dd91bc..5bdd5c6d 100644 --- a/doc/mkdocs.yml +++ b/doc/mkdocs.yml @@ -48,11 +48,14 @@ nav: - Database customization: user-guide/config/database.md - Developer Guide: - Developer guide: dev-guide/README.md + - Architecture: dev-guide/architecture.md - Contributing guide: dev-guide/contributing.md + - Coding style: dev-guide/coding-style.md - Testing policy: dev-guide/testing-policy.md - Code review requirements: dev-guide/code-review-requirements.md - API reference: dev-guide/api.md - Integration guide: dev-guide/integration.md + - FAQ: dev-guide/faq.md - About: - License: about/license.md - Releases: about/releases.md