Skip to content

Commit

Permalink
docs: Move wiki info to GH Pages
Browse files Browse the repository at this point in the history
Signed-off-by: Oleg Kopysov <o.kopysov@samsung.com>
  • Loading branch information
o-kopysov committed Sep 13, 2024
1 parent 2714eda commit 831a81b
Show file tree
Hide file tree
Showing 6 changed files with 244 additions and 0 deletions.
6 changes: 6 additions & 0 deletions doc/docs/dev-guide/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
7 changes: 7 additions & 0 deletions doc/docs/dev-guide/architecture.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Architecture

How LPVS interacts with other entities.

---

![Architecture](../img/architecture.png)
44 changes: 44 additions & 0 deletions doc/docs/dev-guide/coding-style.md
Original file line number Diff line number Diff line change
@@ -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<LPVSFile> scanResult =
- this.runScan(webhookConfig, LPVSDetectService.getPathByPullRequest(webhookConfig));
+ this.runScan(
+ webhookConfig,
+ LPVSDetectService.getPathByPullRequest(webhookConfig));

List<LPVSLicenseService.Conflict<String, String>> 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).
184 changes: 184 additions & 0 deletions doc/docs/dev-guide/faq.md
Original file line number Diff line number Diff line change
@@ -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
<n> = key expires in n days
<n>w = key expires in n weeks
<n>m = key expires in n months
<n>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) <o.kopysov@samsung.com>"

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) <o.kopysov@samsung.com>
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 <key-ID>
```
Create and sign the tag
```bash
git tag -s <tag>
```
### 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 <key-ID>`
### 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 <public key>
```
### Verification signed file
```bash
gpg --verify <signature file> <signed file>
```
!!! note
If you have multiple keys, you must specify the key that will be used by adding the option `-u <key-ID>`
---
## 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.
Binary file added doc/docs/img/architecture.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions doc/mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 831a81b

Please sign in to comment.