diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md deleted file mode 100644 index fef8eb82..00000000 --- a/.github/CONTRIBUTING.md +++ /dev/null @@ -1,104 +0,0 @@ -## Contributing - -If you want to contribute to the LPVS project and make it better, your help is very welcome. Contributing is also a great way to learn more about social coding on GitHub, new technologies, and how to make constructive bug reports, feature requests, and the noblest of all contributions: a good, clean pull request. - -You can use templates to create a description of your [pull request](PULL_REQUEST_TEMPLATE.md) or [issue](ISSUE_TEMPLATE.md), which will greatly simplify the LPVS team's work on reviewing and incorporating your code. However, using these templates is not mandatory, and we will always welcome any help. - -To make a clean pull request, follow the steps below: - -1. [Fork](http://help.github.com/fork-a-repo/) the LPVS repository on GitHub and clone your fork to your development environment: - ```sh - git clone https://github.com/YOUR-GITHUB-USERNAME/LPVS.git - ``` - If you have trouble setting up Git with GitHub in Linux or are getting errors like "Permission Denied (publickey)", you must [set up your Git installation to work with GitHub](http://help.github.com/linux-set-up-git/). - -2. Add the main LPVS repository as an additional Git remote called "upstream": - ```sh - git remote add upstream https://github.com/samsung/lpvs - ``` - -3. Make sure there is an issue created for the task you are working on. All new features and bug fixes should have an associated issue to provide a single point of reference for discussion and documentation. If the issue already exists, leave a comment on that issue indicating that you intend to work on it. If it doesn't exist, open a new issue for your task. - - > For small changes or documentation issues, creating an issue is not necessary, and a pull request is sufficient. - -4. Fetch the latest code from the main LPVS branch: - ```sh - git fetch upstream - ``` - You should start at this point for every new contribution to make sure you are working on the latest code. - -5. Create a new branch for your feature based on the current LPVS main branch: - - Each separate bug fix or feature addition should have its own branch. Branch names should be descriptive and start with the number of the corresponding issue, if applicable. If you're not fixing a specific issue, you can skip the number. - ```sh - git checkout upstream/ - git checkout -b 999-name-of-your-branch-goes-here - ``` - Above, can be '1.0.0', etc. - see the list of releases or `main` branch. - -6. Write your code and make the necessary changes. - - Follow the coding conventions and style guidelines used in the LPVS project. - - Write clear, concise, and well-documented code. - - Include unit tests to ensure the correctness of your code. - - If you're adding a new feature, consider updating the relevant documentation and examples. - - If you're fixing a bug, provide a clear explanation of the issue and how your code resolves it. - - Feel free to reach out if you have any further questions or need additional assistance! - -7. Commit your changes with a descriptive commit message. Make sure to mention the issue number with `#XXX` so that GitHub will automatically link your commit with the issue. Additionally, use appropriate commit message prefixes to categorize your changes. - - - **feat**: Introduce a new feature or enhancement. - - **fix**: Address a bug or resolve an issue. - - **chore**: Perform routine tasks or maintenance. - - **docs**: Make changes to documentation. - - **style**: Implement code style changes (e.g., formatting). - - **test**: Modify or add tests. - - **refactor**: Implement code refactoring. - - **perf**: Performance Improvements. - - **build**: Any changes in build conditions. - - **ci**: Implement any continuous integration changes. - - **revert**: Revert to previous code state. - - For example: - - ```sh - git add path/to/my/file - git commit -m "feat: A brief description of this new feature which resolves #42" --signoff - git commit -m "fix: A brief description of this bug fix which fixes #42" --signoff - git commit -m "chore: A brief description of routine tasks or maintenance" --signoff - git commit -m "docs: A brief description of documentation changes" --signoff - git commit -m "style: A brief description of code style changes (e.g., formatting)" --signoff - git commit -m "test: A brief description of changes related to testing" --signoff - git commit -m "refactor: A brief description of code refactoring" --signoff - git commit -m "perf: A brief description of performance improvements" --signoff - git commit -m "build: A brief description of build conditions" --signoff - git commit -m "ci: A brief description of continuous integration changes" --signoff - git commit -m "revert: A brief description of revert previous code state" --signoff - ``` - -8. Pull the latest LPVS code from upstream into your branch: - ```sh - git rebase upstream/main - ``` - -9. Push your code to your forked repository: - ```sh - git push -u origin my-feature - ``` - `-u` parameter ensures that your branch will now automatically push and pull from the GitHub branch. That means if you type `git push` next time, it will know where to push to. - -10. Open a pull request against the upstream repository. Go to your repository on GitHub and click "Pull Request". Choose your branch on the right and enter some more details in the comment box. To link the pull request to the issue, include `#999` in the pull request comment, where 999 is the issue number. - > Note that each pull-request should fix a single change. - -11. Someone from the LPVS team will review your code, and you might be asked to make some changes. If requested, make the necessary changes and push them to your branch. The pull request will be updated automatically. - -12. Once your code is accepted, it will be merged into the main branch and become part of the next LPVS release. If your code is not accepted, don't be discouraged. LPVS aims to meet specific requirements and priorities, and your contribution will still be available on GitHub as a reference for others. - -13. After your contribution is merged or declined, you can delete the branch you've worked on from your local repository and your forked repository: - ```sh - git checkout main - git branch -D my-feature - git push origin --delete my-feature - ``` - -Thank you for your contribution to LPVS! \ No newline at end of file diff --git a/.gitignore b/.gitignore index 68b3286c..4baddf3b 100644 --- a/.gitignore +++ b/.gitignore @@ -28,3 +28,6 @@ target/ LPVS/Projects/ LPVS/Results/ *.iml + +# MkDocs generated website +doc/site/ diff --git a/LICENSE b/LICENSE index e3805bcb..69675b91 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright (c) 2022, Samsung Research. All rights reserved. +Copyright (c) 2022, Samsung Electronics Co., Ltd. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 15ebdcd4..056fbb7c 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -![Logo for dark mode](doc/lpvs-dark.png#gh-dark-mode-only) -![Logo for light mode](doc/lpvs-light.png#gh-light-mode-only) +![Logo for dark mode](doc/docs/img/lpvs-dark.png#gh-dark-mode-only) +![Logo for light mode](doc/docs/img/lpvs-light.png#gh-light-mode-only) # License Pre-Validation Service @@ -74,8 +74,8 @@ The _LPVS_ source code is distributed under the [MIT](https://opensource.org/lic You are welcome to contribute to the _LPVS_ project. Contributing is a great way to practice social coding on GitHub, learn new technologies, and enhance your public portfolio. If you would like to contribute, please follow the guidelines below: -- [How to Contribute Code](.github/CONTRIBUTING.md) +- [How to Contribute Code](doc/docs/dev-guide/contributing.md) - [How to Report a Security Vulnerability](.github/SECURITY.md) -- [Code Review Requirements](doc/code-review-requirements.md) +- [Code Review Requirements](doc/docs/dev-guide/code-review-requirements.md) Thank you for your interest in contributing to _LPVS_! Your contributions are highly appreciated. diff --git a/doc/code-review-requirements.md b/doc/code-review-requirements.md deleted file mode 100644 index 290084ce..00000000 --- a/doc/code-review-requirements.md +++ /dev/null @@ -1,64 +0,0 @@ -# Code review requirements - -## Contents -1. [Introduction](#1-introduction) -2. [Code Review Process](#2-code-review-process) -3. [Requirements](#3-requirements) -4. [Check list](#4-check-list) - -## 1. Introduction -Code review is a process in which one or more developers are systematically tasked with reviewing the code written by another developer in order to find defects and improve it. Code review should be done by project maintainers considering code quality and safety, sharing best practices and this leads to better collaboration, creating a culture of review, building team confidence in the code. - -## 2. Code Review Process - -1. **Initiating a Code Review:** - - All code changes must undergo a review before merging into the main branch. - - The developer initiates a code review by creating a pull request. -2. **Assigning Reviewers:** - - The pull request is automatically assigned to maintainers for review. - - Other team members should be added manually for review. -3. **Reviewing Code:** - - Reviewers are responsible for thoroughly examining the code changes. - - Check for adherence to coding standards, best practices, and project guidelines. -4. **Providing Constructive Feedback:** - - Reviewers must provide clear and constructive feedback on identified issues or improvements. - - Discussions within the pull request are encouraged to ensure a shared understanding. - -## 3. Requirements - - * Review fewer than 400 lines of code at a time. - * Take your time. Inspection rates should under 500 LOC per hour. - * Do not review for more than 60 minutes at a time. - * Set goals and capture metrics. - * Authors should annotate source code before the review. - * Use checklists. - * Establish a process for fixing defects found. - * Foster a positive code review culture. - * Embrace the subconscious implications of peer review. - * Practice lightweight code reviews. - * Code changes must receive approval from at least two team members before merging. - * **At least one maintainer's approval is required.** - * Critical issues raised during the review must be addressed before approval. - * Non-blocking feedback should be addressed in subsequent iterations. - * Pull requests should be kept focused on specific features or fixes. - * Continuous improvement in code quality is encouraged. - - -## 4. Check list -- [ ] **Coding Standards:** - - Ensure the code follows the established coding standards. - -- [ ] **Functionality:** - - Verify that the code changes address the intended functionality or issue. - -- [ ] **Edge Cases:** - - Check for handling of edge cases and potential error scenarios. - -- [ ] **Testing:** - - Confirm that appropriate tests have been added or updated. - -- [ ] **Documentation:** - - Validate that code changes are well-documented, including inline comments and README updates. - -- [ ] **Security:** - - Assess the code for potential security vulnerabilities. \ No newline at end of file diff --git a/doc/docs/about/license.md b/doc/docs/about/license.md new file mode 100644 index 00000000..f2481fd7 --- /dev/null +++ b/doc/docs/about/license.md @@ -0,0 +1,27 @@ +# License + +The legal stuff. + +--- + +## LPVS License (MIT) + +Copyright (c) 2022, Samsung Electronics Co., Ltd. All rights reserved. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/doc/docs/about/releases.md b/doc/docs/about/releases.md new file mode 100644 index 00000000..67d82742 --- /dev/null +++ b/doc/docs/about/releases.md @@ -0,0 +1,31 @@ +# Releases + +Where to get the latest released version of LPVS. + +--- + +## Used version + +You can determine your currently used version of LPVS by running the next command in console and checking the logs: + +```console +$ java -jar lpvs-x.y.z.jar +``` +![Version of LPVS](../img/version.png) + +## Latest releases + +Actual releases with release notes are available on [GitHub](https://github.com/Samsung/LPVS/releases). + +## Maintenance team + +The current and past members of the LPVS team. + +* [@MoonkiHong](https://github.com/MoonkiHong/) +* [@tiokim](https://github.com/tiokim/) +* [@o-kopysov](https://github.com/o-kopysov/) +* [@tdrozdovsky](https://github.com/tdrozdovsky/) +* [@m-rudyk](https://github.com/m-rudyk/) +* [@v-kerimov](https://github.com/v-kerimov/) +* [@o-konoval](https://github.com/o-konoval/) +* [@t-naumenko](https://github.com/t-naumenko/) diff --git a/doc/docs/css/extra.css b/doc/docs/css/extra.css new file mode 100644 index 00000000..7dcbe47c --- /dev/null +++ b/doc/docs/css/extra.css @@ -0,0 +1,89 @@ +div.col-md-9 h1:first-of-type { + text-align: center; + font-size: 60px; + font-weight: 300; +} + +div.col-md-9>p:first-of-type { + text-align: center; +} + +div.col-md-9 p.admonition-title:first-of-type { + text-align: left; +} + +div.col-md-9 h1:first-of-type .headerlink { + display: none; +} + +div.admonition.block>.admonition-title { + display: none; +} + +.admonition.new, details.new { + color: var(--bs-success-text-emphasis); + background-color: var(--bs-success-bg-subtle); + border-color: var(--bs-success-border-subtle); +} +.admonition.example, details.example { + color: var(--bs-info-text-emphasis); + background-color: var(--bs-info-bg-subtle); + border-color: var(--bs-info-border-subtle); +} + +/* Definition List styles */ + +dd { + padding-left: 20px; +} + +.card-body svg { + width: 100%; + padding: 0 50px; + height: auto; +} + +/* Homepage */ + +body.homepage>div.container>div.row>div.col-md-3 { + display: none; +} + +body.homepage>div.container>div.row>div.col-md-9 { + margin-left: 0; + flex: 0 0 100%; + max-width: 100%; +} + +/* mkdocstrings */ + +.doc-object { + padding-left: 10px; + border-left: 4px solid var(--bs-light-border-subtle); +} + +.doc-contents .field-body p:first-of-type { + display: inline; +} + +.doc-label-class-attribute, +.doc-label-instance-attribute { + display: none; +} + +h2.doc-heading { + font-size: 1.5rem; +} +h3.doc-heading { + font-size: 1.4rem; +} +h4.doc-heading { + font-size: 1.3rem; +} +h5.doc-heading { + font-size: 1.2rem; +} + +.doc-contents { + padding-left: 0; +} diff --git a/doc/docs/dev-guide/README.md b/doc/docs/dev-guide/README.md new file mode 100644 index 00000000..69ace2da --- /dev/null +++ b/doc/docs/dev-guide/README.md @@ -0,0 +1,21 @@ +# Developer Guide + +Extending LPVS + +--- + +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. + +- [Contributing guide] +- [Testing policy] +- [Code review requirements] +- [API reference] +- [Integration guide] + +[Contributing guide]: contributing.md +[Testing policy]: testing_policy.md +[Code review requirements]: code-review-requirements.md +[API reference]: api.md +[Integration guide]: integration.md \ No newline at end of file diff --git a/doc/docs/dev-guide/code-review-requirements.md b/doc/docs/dev-guide/code-review-requirements.md new file mode 100644 index 00000000..375bb97c --- /dev/null +++ b/doc/docs/dev-guide/code-review-requirements.md @@ -0,0 +1,67 @@ +# Code review requirements + +How to conduct code reviews in the LPVS project. + +--- + +## Introduction +Code review is a process in which one or more developers are systematically tasked with reviewing +the code written by another developer in order to find defects and improve it. Code review should +be done by project maintainers considering code quality and safety, sharing best practices and this +leads to better collaboration, creating a culture of review, building team confidence in the code. + +--- + +## Code Review Process + +**Initiating a Code Review** + + - All code changes must undergo a review before merging into the main branch. + - The developer initiates a code review by creating a pull request. + +**Assigning Reviewers** + + - The pull request is automatically assigned to maintainers for review. + - Other team members should be added manually for review. + +**Reviewing Code** + + - Reviewers are responsible for thoroughly examining the code changes. + - Check for adherence to coding standards, best practices, and project guidelines. + +**Providing Constructive Feedback** + + - Reviewers must provide clear and constructive feedback on identified issues or improvements. + - Discussions within the pull request are encouraged to ensure a shared understanding. + +--- + +## Requirements + +* Review fewer than 400 lines of code at a time. +* Take your time. Inspection rates should under 500 LOC per hour. +* Do not review for more than 60 minutes at a time. +* Set goals and capture metrics. +* Authors should annotate source code before the review. +* Use checklists. +* Establish a process for fixing defects found. +* Foster a positive code review culture. +* Embrace the subconscious implications of peer review. +* Practice lightweight code reviews. +* Code changes must receive approval from at least two team members before merging. +* **At least one maintainer's approval is required.** +* Critical issues raised during the review must be addressed before approval. +* Non-blocking feedback should be addressed in subsequent iterations. +* Pull requests should be kept focused on specific features or fixes. +* Continuous improvement in code quality is encouraged. + +--- + +## Self-verification Checklist + +- [ ] **Coding Standards**: ensure the code follows the established coding standards. +- [ ] **Functionality**: verify that the code changes address the intended functionality or issue. +- [ ] **Edge Cases**: check for handling of edge cases and potential error scenarios. +- [ ] **Testing**: confirm that appropriate tests have been added or updated. +- [ ] **Documentation**: validate that code changes are well-documented, including inline comments and README updates. +- [ ] **Security**: assess the code for potential security vulnerabilities. \ No newline at end of file diff --git a/doc/docs/dev-guide/contributing.md b/doc/docs/dev-guide/contributing.md new file mode 100644 index 00000000..1cee7c2d --- /dev/null +++ b/doc/docs/dev-guide/contributing.md @@ -0,0 +1,182 @@ +# Contributing + +An introduction to contributing to the LPVS project. + +--- + +We welcome contributions! By contributing, you can help improve this project and make it better for everyone. + +## Ways to Contribute + +Here are some ways you can contribute to this project: + +- **Report Bugs & Request Features** 🐛💡: Let us know if you find any bugs or have ideas + for new features by [creating an issue]. +- **Vulnerability Reporting** 🚨: If you discover a vulnerability in our project, please report it according to + the [Security guideline]. +- **Code Contributions** 🛠️: Fix bugs, add new features, or improve the existing code. +- **Documentation** 📝: Improve our documentation by correcting typos, clarifying instructions, + or adding new content. +- **Code Reviews** 🔍: Review other contributors' [pull requests] to maintain code quality. + +--- + +## Code Contribution + +If you want to contribute to the LPVS project and make it better, your help is very welcome. +Contributing is also a great way to learn more about social coding on GitHub, new technologies, +and how to make constructive bug reports, feature requests, and the noblest of all contributions: +a good, clean pull request. + +!!! note + + You can use templates to create a description of your pull request or issue, which will greatly + simplify the LPVS team's work on reviewing and incorporating your code. However, using these + templates is not mandatory, and we will always welcome any help. + +To make a clean pull request, follow the steps below: + +* [Fork](http://help.github.com/fork-a-repo/) the LPVS repository on GitHub and clone your fork +to your development environment. + +```bash +git clone https://github.com/YOUR-GITHUB-USERNAME/LPVS.git +``` + +!!! warning + + If you have trouble setting up Git with GitHub in Linux or are getting errors like `Permission + Denied (publickey)`, you must [set up your Git installation to work with GitHub](http://help.github.com/linux-set-up-git/). + +* Add the main LPVS repository as an additional Git remote called `upstream`. + +```bash +git remote add upstream https://github.com/samsung/lpvs +``` + +* Make sure there is an issue created for the task you are working on. All new features and bug +fixes should have an associated issue to provide a single point of reference for discussion and documentation. +If the issue already exists, leave a comment on that issue indicating that you intend to work on it. +If it doesn't exist, open a new issue for your task. + +!!! note + + For small changes or documentation issues, creating an issue is not necessary, + and a pull request is sufficient. + +* Fetch the latest code from the main LPVS branch. + +```bash +git fetch upstream +``` + +!!! warning + + You should start at this point for every new contribution to make sure you are working + on the latest code. + +* Create a new branch for your feature based on the current LPVS main branch. Each separate bug fix +or feature addition should have its own branch. Branch names should be descriptive and start with +the number of the corresponding issue, if applicable. If you're not fixing a specific issue, you +can skip the number. + +```bash +git checkout upstream/ +git checkout -b 999-name-of-your-branch-goes-here +``` + +!!! info + + Above, can be '1.0.0', etc. - see the list of releases or `main` branch. + +* Write your code and make the necessary changes. + + - Follow the coding conventions and style guidelines used in the LPVS project. + - Write clear, concise, and well-documented code. + - Include unit tests to ensure the correctness of your code. + - If you're adding a new feature, consider updating the relevant documentation and examples. + - If you're fixing a bug, provide a clear explanation of the issue and how your code resolves it. + +* Commit your changes with a descriptive commit message. Make sure to mention the issue number +with `#XXX` so that GitHub will automatically link your commit with the issue. Additionally, use +appropriate commit message prefixes to categorize your changes. + + - **feat**: Introduce a new feature or enhancement. + - **fix**: Address a bug or resolve an issue. + - **chore**: Perform routine tasks or maintenance. + - **docs**: Make changes to documentation. + - **style**: Implement code style changes (e.g., formatting). + - **test**: Modify or add tests. + - **refactor**: Implement code refactoring. + - **perf**: Performance Improvements. + - **build**: Any changes in build conditions. + - **ci**: Implement any continuous integration changes. + - **revert**: Revert to previous code state. + +For example: + +```bash +git add path/to/my/file +git commit -m "feat: A brief description of this new feature which resolves #42" --signoff +git commit -m "fix: A brief description of this bug fix which fixes #42" --signoff +git commit -m "chore: A brief description of routine tasks or maintenance" --signoff +git commit -m "docs: A brief description of documentation changes" --signoff +git commit -m "style: A brief description of code style changes (e.g., formatting)" --signoff +git commit -m "test: A brief description of changes related to testing" --signoff +git commit -m "refactor: A brief description of code refactoring" --signoff +git commit -m "perf: A brief description of performance improvements" --signoff +git commit -m "build: A brief description of build conditions" --signoff +git commit -m "ci: A brief description of continuous integration changes" --signoff +git commit -m "revert: A brief description of revert previous code state" --signoff +``` + +* Pull the latest LPVS code from upstream into your branch. + +```bash +git rebase upstream/main +``` + +* Push your code to your forked repository. + +```bash +git push -u origin my-feature +``` + +!!! note + + `-u` parameter ensures that your branch will now automatically push and pull from the GitHub branch. That means if you type `git push` next time, it will know where to push to. + +* Open a pull request against the upstream repository. Go to your repository on GitHub and click `Pull Request`. +Choose your branch on the right and enter some more details in the comment box. To link the pull request +to the issue, include `#999` in the pull request comment, where 999 is the issue number. + +!!! info + + Each pull-request should fix a single change. + +* Someone from the LPVS team will review your code, and you might be asked to make some changes. If requested, +make the necessary changes and push them to your branch. The pull request will be updated automatically. + +* Once your code is accepted, it will be merged into the main branch and become part of the next LPVS release. +If your code is not accepted, don't be discouraged. LPVS aims to meet specific requirements and priorities, +and your contribution will still be available on GitHub as a reference for others. + +* After your contribution is merged or declined, you can delete the branch you've worked on from your local +repository and your forked repository: + +```bash +git checkout main +git branch -D my-feature +git push origin --delete my-feature +``` + +--- + +## Code of Conduct + +Everyone interacting in the LPVS project's codebases and issue trackers is expected to follow the [Code of Conduct]. + +[Code of Conduct]: https://github.com/Samsung/LPVS?tab=coc-ov-file +[creating an issue]: https://github.com/Samsung/LPVS/issues/new/choose +[Security guideline]: https://github.com/Samsung/LPVS?tab=security-ov-file +[pull requests]: https://github.com/Samsung/LPVS/pulls \ No newline at end of file diff --git a/doc/docs/dev-guide/testing_policy.md b/doc/docs/dev-guide/testing_policy.md new file mode 100644 index 00000000..c65fe422 --- /dev/null +++ b/doc/docs/dev-guide/testing_policy.md @@ -0,0 +1,49 @@ +# Testing policy + +How to check verify correct work of LPVS. + +--- + +## Introduction + +Testing is a very important part of LPVS project and our team values it highly. + +**When adding or changing functionality, the main requirement is to include new tests as part of your contribution.** + +!!! note + + If your contribution does not have the required tests, please mark this in the PR and our team will support + to develop them. + +The LPVS team strives to maintain test coverage of **at least 70%**. We ask you to help us keep this minimum. +Additional tests are very welcome. + +The LPVS team strongly recommends adhering to the [Test-driven development (TDD)](https://en.wikipedia.org/wiki/Test-driven_development) as a software development +process. + +--- + +## How to start Test Suite (Local) + +To build and testing all packages: + +```bash +mvn -B package -Pcoverage --file pom.xml +``` + +To start testing all packages: + +```bash +mvn test +``` + +--- + +## Automated Run Test Suite (Remote) + +Code testing occurs remotely using an [Actions -> Workflow Test-suite](https://github.com/Samsung/LPVS/actions/workflows/test-suite.yml) +during each `push` or `pull_request`. + +!!! info + + Find more information on [GitHub Actions documentation](https://docs.github.com/en/actions) diff --git a/doc/lpvs-dark.png b/doc/docs/img/lpvs-dark.png similarity index 100% rename from doc/lpvs-dark.png rename to doc/docs/img/lpvs-dark.png diff --git a/doc/lpvs-light.png b/doc/docs/img/lpvs-light.png similarity index 100% rename from doc/lpvs-light.png rename to doc/docs/img/lpvs-light.png diff --git a/doc/docs/img/version.png b/doc/docs/img/version.png new file mode 100644 index 00000000..f9032928 Binary files /dev/null and b/doc/docs/img/version.png differ diff --git a/doc/docs/index.md b/doc/docs/index.md new file mode 100644 index 00000000..c200ea0c --- /dev/null +++ b/doc/docs/index.md @@ -0,0 +1,36 @@ +![Logo for light mode](img/lpvs-light.png) + +# License Pre-Validation Service (LPVS) + +--- +## Introduction +[Open-source code](https://en.wikipedia.org/wiki/Open-source_software) (that is a software that is freely available for use, study, modification, and distribution) must meet conditions of the respective license(s) of all of its dependencies. Miscompliance may lead to legal disputes, fines, obligation to disclose intellectual property, as well as reputational damage. + +In projects with numerous external dependencies, it becomes challenging to track license obligations accurately. Also, when many collaborators are involved, the risk of unintentional license violations, such as through copy-pasting code snippets, increases. Furthermore, there are nuanced situations like dependencies with dual licensing or licenses that may change due to ownership, purpose, or legislative alterations. These factors can potentially turn previously safe dependencies into unsafe ones over time. + +To address these license-related risks for open-source code, we have developed the _License Pre-Validation Service (LPVS)_. This tool provides a solution to mitigate potential license issues. By analyzing the project, _LPVS_ identifies its components and their respective licenses at every commit. Then it generates a list of potential issue cases, and communicates them to the developers as comments on GitHub. _LPVS_ offers a comprehensive description of possible license violations, including the details on the location of risky code and an overview of the specific license-related issues. + +With _LPVS_, we aim at assisting developers and project teams with ensuring license compliance for their open-source code. By providing insights into the potential license violations and their implications, _LPVS_ enables proactive management of license-related risks throughout the development process. + +We believe that _LPVS_ will be an invaluable tool for maintaining the integrity of open-source projects and safeguarding against license infringements. + +--- +## Features + +- **License Scanners**: + + _LPVS_ integrates with the [SCANOSS](https://www.scanoss.com) license scanner, allowing for comprehensive license analysis of the project's components. SCANOSS helps to identify the licenses associated with the codebase, ensuring the compliance with open-source license requirements. By leveraging SCANOSS, _LPVS_ provides accurate and up-to-date information on the licenses used in the project. + +- **GitHub Review System Integration**: + + _LPVS_ seamlessly integrates with the GitHub review system, enhancing the collaboration and code review process. _LPVS_ automatically generates comments on GitHub, highlighting potential license violations or issues within the codebase. This integration streamlines the review process, making it easier for the developers and collaborators to identify and address license-related concerns directly within the GitHub environment. + +- **Continuous Monitoring**: + + _LPVS_ facilitates continuous monitoring of license-related risks throughout the development process. By analyzing each commit, _LPVS_ ensures that any changes or additions to the codebase are assessed for potential license violations. This ongoing monitoring allows developers to proactively manage license compliance and address any issues that arise in a timely manner. + +- **Risk Mitigation**: + + _LPVS_ aims at mitigating license-related risks by providing early detection and identification of potential violations. By alerting developers about potential issues and by providing the necessary information to understand and address them, _LPVS_ empowers teams to take proactive steps to ensure compliance with open-source licenses. This helps mitigate the risk of legal disputes, financial liabilities, and reputational damage associated with license violations. + +With these features, _LPVS_ assists developers to manage license compliance for their open-source projects effectively. By integration with license scanning tools, supporting the GitHub review system, and providing comprehensive issue descriptions, _LPVS_ offers a robust solution for identifying and addressing license-related risks in the software development lifecycle. diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml new file mode 100644 index 00000000..f064d665 --- /dev/null +++ b/doc/mkdocs.yml @@ -0,0 +1,55 @@ +site_name: License Pre-Validation Service +site_url: https://samsung.github.io/LPVS/ +site_description: License Pre-Validation Service (LPVS) Documentation + +repo_url: https://github.com/Samsung/LPVS +edit_uri: blob/main/doc/docs/ + +theme: + name: mkdocs + color_mode: auto + user_color_mode_toggle: true + locale: en + highlightjs: true + +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.superfences + - pymdownx.tasklist: + clickable_checkbox: true + +nav: + - Home: index.md + #- Getting Started: getting-started.md + #- User Guide: user-guide + - Developer Guide: + - Developer guide: dev-guide/README.md + - Contributing guide: dev-guide/contributing.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 + - About: + - License: about/license.md + - Releases: about/releases.md + +extra_css: + - css/extra.css + +exclude_docs: | + *.py + +use_directory_urls: true + +#extra: +# # files to be copied from repository root to docs_path +# files_to_copy: +# - contributing.md +# # path to documentation root +# docs_path: docs/about + +#hooks: +# - docs/hooks.py + +copyright: Copyright © 2024, Samsung Electronics Co., Ltd. All rights reserved. diff --git a/doc/overview.html b/doc/overview.html deleted file mode 100644 index 24647549..00000000 --- a/doc/overview.html +++ /dev/null @@ -1,49 +0,0 @@ - - - - - - - - License Pre-Validation Service (LPVS) Overview - - - -LPVS Logo -

License Pre-Validation Service

- -

Introduction

- -

Open-source code refers to software that is freely available for use, study, modification, and distribution, subject to meeting the conditions of the corresponding license. Failure to comply with the license conditions can lead to legal disputes, financial liabilities, the requirement to disclose intellectual property, and reputational damage.

- -

In projects with numerous external dependencies, accurately tracking license obligations can be challenging. The risk of unintentional license violations, especially in collaborative projects, increases. The License Pre-Validation Service (LPVS) addresses these license-related risks by analyzing the project, identifying components and their licenses at every commit, and generating a list of potential issues communicated as comments on GitHub.

- -

LPVS assists developers and project teams in ensuring license compliance for their open-source code by providing insights into potential license violations and their implications.

- -

Features

- -
    -
  • License Scanners: LPVS integrates with the SCANOSS license scanner for comprehensive license analysis, ensuring compliance with open-source license requirements.
    • - -
  • GitHub Review System Integration: Seamless integration with GitHub review system, automatically generating comments to highlight potential license violations or issues.
    • - -
  • Comprehensive Issue Description: LPVS provides detailed descriptions of possible license violations, including specific information on risky code locations and an overview of license-related issues.
    • - -
  • Continuous Monitoring: Facilitates continuous monitoring of license-related risks throughout the development process by analyzing each commit for potential violations.
    • - -
  • Risk Mitigation: Aims to mitigate license-related risks through early detection, identification of potential violations, and providing information to understand and address them.
    • -
- -

License

- -

The LPVS source code is distributed under the MIT open source license.

- - - diff --git a/doc/testing_policy.md b/doc/testing_policy.md deleted file mode 100644 index 0401218a..00000000 --- a/doc/testing_policy.md +++ /dev/null @@ -1,41 +0,0 @@ -# Testing policy -## Contents -1. [Introduction](#1-introduction) -2. [How to start Test Suite (Local)](#2-how-to-start-test-suite-local) -3. [Automated Run Test Suite (Remote)](#3-automated-run-test-suite-remote) - ---- - -## 1. Introduction - -Testing is a very important part of LPVS project and our team values it highly. - -**When adding or changing functionality, the main requirement is to include new tests as part of your contribution.** -> If your contribution does not have the required tests, please mark this in the PR and our team will support to develop them. - -The LPVS team strives to maintain test coverage of **at least 70%**. We ask you to help us keep this minimum. Additional tests are very welcome. - -The LPVS team strongly recommends adhering to the [Test-driven development (TDD)](https://en.wikipedia.org/wiki/Test-driven_development) as a software development process. - ---- - -## 2. How to start Test Suite (Local) - -To build and testing all packages: -``` -mvn -B package -Pcoverage --file pom.xml -``` -To start testing all packages: -``` -mvn test -``` - ---- - -## 3. Automated Run Test Suite (Remote) - -Code testing occurs remotely using a [github->actions->workflow (Test-suite)](https://github.com/Samsung/LPVS/actions/workflows/test-suite.yml) during each `push` or `pull_request`. - -> [More information on github->actions](https://docs.github.com/en/actions) - ----