diff --git a/community/CONTRIBUTING.md b/community/CONTRIBUTING.md index 7da855f3..37e230ae 100644 --- a/community/CONTRIBUTING.md +++ b/community/CONTRIBUTING.md @@ -370,7 +370,7 @@ The OPEA projects use GitHub Action for CI test. - End to End Test, the PR must pass all end to end tests. #### Pull Request Review -You can add reviewers from [the code owners list](../codeowner.md) to your PR. +You can add reviewers from [the code owners list](./codeowner.md) to your PR. ## Support diff --git a/community/ContributionGuidelines.txt b/community/ContributionGuidelines.txt deleted file mode 100755 index 318aa5de..00000000 --- a/community/ContributionGuidelines.txt +++ /dev/null @@ -1,951 +0,0 @@ -# Contribution Guidelines - -Thanks for considering contributing to the OPEA project. The contribution -process is similar with other open source projects on Github, involving an -amount of open discussion about issues and feature requests between the -maintainers, contributors, and users. - -As an open-source project, we welcome and encourage the community to submit -patches directly to the project. In our collaborative open source environment, -standards and methods for submitting changes help reduce the chaos that can -result from an active development community. - -This document explains how to participate in project conversations, log bugs and -enhancement requests, and submit patches to the project so your patch will be -accepted quickly in the codebase. - -## Support - -- Feel free to reach out to [opea@opea.dev](mailto: info@opea.dev) for support. -- Submit your questions, feature requests, and bug reports to the GitHub issues page. - -## Contributor Covenant Code of Conduct - -This project is intended to be a safe, welcoming space for collaboration, and -contributors are expected to adhere to the -[Contributor Covenant Code of Conduct](./CODE_OF_CONDUCT.md). - - -## Community Discussions - -Developers are encouraged to participate in discussions by opening an issue in -one of the GitHub repos at -[github.com/opea-project](https://github.com/opea-project). Alternatively, send -an email to [info@opea.dev](mailto:info@opea.dev) or subscribe to -[X/Twitter](https://twitter.com/opeadev) or -[LinkedIn](https://www.linkedin.com/company/opeadev/posts/?feedView=all) to get -the latest updates about the OPEA project. - -## Documentation - -The quality of OPEA project's documentation can have a huge impact on its -success. We reply on OPEA maintainers and contributors to build clear, detailed, -and update-to-date documentation for user. - - -## Licensing - -Licensing is very important to open source projects. It helps ensure the -software continues to be available under the terms that the author desired. - -.. _Apache 2.0 license: - https://github.com/opea-project/License/blob/main/LICENSE.txt - -.. _GitHub repo: https://github.com/opea-project - -OPEA uses the [Apache 2.0 license](https://github.com/opea-project/License/blob/main/LICENSE.txt) -(as found in the LICENSE file in -the project's [GitHub repos](https://github.com/opea-project) to strike a balance between open -contribution and allowing you to use the software however you would like -to. The Apache 2.0 license is a permissive open source license that -allows you to freely use, modify, distribute, and sell your own products -that include Apache 2.0 licensed software. - -A license tells you what rights you have as a developer, as provided by the -copyright holder. It is important that the contributor fully understands the -licensing rights and agrees to them. Sometimes the copyright holder isn't the -contributor, such as when the contributor is doing work on behalf of a -company. - -### Components using other Licenses - -Importing code into the OPEA project from other projects that use a license -other than the Apache 2.0 license needs to be fully understood in -context and approved by the OPEA governing board. - -By carefully reviewing potential contributions and also enforcing a -DCO for contributed code, we can ensure that -the OPEA community can develop products with the OPEA Project -without concerns over patent or copyright issues. - -## Copyrights Notices - -Please follow this [Community Best Practice](https://www.linuxfoundation.org/blog/copyright-notices-in-open-source-software-projects/) -for Copyright Notices from the Linux Foundation. - -## Developer Certification of Origin (DCO) - -To make a good faith effort to ensure licensing criteria are met, the OPEA -project requires the Developer Certificate of Origin (DCO) process to be -followed. - -The DCO is an attestation attached to every contribution made by every -developer. In the commit message of the contribution, (described more fully -later in this document), the developer simply adds a ``Signed-off-by`` -statement and thereby agrees to the DCO. - -When a developer submits a patch, it is a commitment that the contributor has -the right to submit the patch per the license. The DCO agreement is shown -below and at [developercertificate.org](http://developercertificate.org/). - -``` -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the - best of my knowledge, is covered under an appropriate open - source license and I have the right under that license to - submit that work with modifications, whether created in whole - or in part by me, under the same open source license (unless - I am permitted to submit under a different license), as - Indicated in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including - all personal information I submit with it, including my - sign-off) is maintained indefinitely and may be redistributed - consistent with this project or the open source license(s) - involved. -``` - -### DCO Sign-Off - -The sign-off in the DCO is a `Signed-off-by:` line in each commit's log -message. The Signed-off-by: line must be in the following format: - -``` -Signed-off-by: Your Name -``` - -For your commits, replace: - -- `Your Name` with your legal name (pseudonyms, hacker handles, and the - names of groups are not allowed) - -- `your.email@example.com` with the same email address you are using to - author the commit (CI will fail if there is no match) - -You can automatically add the Signed-off-by: line to your commit body using -`git commit -s`. Use other commits in the opea git history as examples. - -Additional requirements: - -- If you are altering an existing commit created by someone else, you must add - your Signed-off-by: line without removing the existing one. - -- If you forget to add the Signed-off-by: line, you can add it to your previous - commit by running `git commit --amend -s`. - -- If you've pushed your changes to GitHub already you'll need to force push - your branch after this with `git push -f`. - -### Notes - -Any contributions made as part of submitted pull requests are considered free -for the Project to use. Developers are permitted to cherry-pick patches that -are included in pull requests submitted by other contributors. It is expected -that - -* the content of the patches will not be substantially modified, -* the cherry-picked commits or portions of a commit shall preserve the original - sign-off messages and the author identity. - - -## Prerequisites - -As a contributor, you'll want to be familiar with the OPEA project, how to -configure, install, and use it and how to set up your development environment. - -You should be familiar with common developer tools such as Git, and -platforms such as GitHub. - - -## Proposing New Features - -OPEA communities use the RFC (request for comments) process for collaborating on -substantial changes to OPEA projects. The RFC process allows the contributors -to collaborate during the design process, providing clarity and validation -before jumping to implementation. - -The RFC process is necessary for changes which have a substantial impact on end -users, workflow, or user facing API. - -It generally includes: - -- Changes to core workflow. -- Changes with significant architectural implications. -- changes which modify or introduce user facing interfaces. - -It is not necessary for changes like: - -- Bug fixes and optimizations with no semantic change. -- Small features which do not involve workflow or interface changes, and only impact a narrow use case. - -Step-by-Step guidelines -####################### - -- Follow the [RFC Template](./rfc_template.md) to propose your idea. -- Submit the proposal to the `Issues` page of the corresponding OPEA github repository. -- Reach out to your RFC's assignee if you need any help with the RFC process. -- Amend your proposal in response to reviewer's feedback. - - -Pull Requests and Issues -************************ - -Submitting Pull Requests -######################## - -Create Pull Request -################### - -If you have improvements to OPEA projects, send your pull requests to each project for review. -If you are new to GitHub, view the pull request [How To](https://help.github.com/articles/using-pull-requests/). - -Step-by-Step guidelines -####################### - -- Star this repository using the button `Star` in the top right corner. -- Fork the corresponding OPEA repository using the button `Fork` in the top right corner. -- Clone your forked repository to your pc by running `git clone "url to your repo"` -- Create a new branch for your modifications by running `git checkout -b new-branch` -- Add your files with `git add -A`, commit `git commit -s -m "This is my commit message"` and push `git push origin new-branch`. -- Create a `pull request` for the project you want to contribute. - - -Pull Request Template -##################### - -See [PR template](./pull_request_template.md) - -Pull Request Acceptance Criteria -################################ - -- At least two approvals from reviewers - -- All detected status checks pass - -- All conversations solved - -- Third-party dependency license compatible - -Pull Request Status Checks Overview -################################### - -The OPEA projects use GitHub Action for CI test. - -| Test Name | Test Scope | Test Pass Criteria | -|--------------------|-------------------------------------------|--------------------| -| DCO | Use `git commit -s` to sign off | PASS | -| Code Format Scan | pre-commit.ci [Bot] | PASS | -| Code Security Scan | Bandit/Hadolint/Dependabot/CodeQL/Trellix | PASS | -| Unit Test | Unit test under test folder | PASS | -| End to End Test | End to end test workflow | PASS | - -- [Developer Certificate of Origin (DCO)](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin), the PR must agree to the terms of Developer Certificate of Origin by signing off each of commits with `-s`, e.g. `git commit -s -m 'This is my commit message'`. -- Unit Test, the PR must pass all unit tests and without coverage regression. -- End to End Test, the PR must pass all end to end tests. - - If the PR introduces new microservice for `GenAIComps`, the PR must include new end to end tests. The test script name should match with the folder name so the test will be automatically triggered by test structure, for examples, if the new service is `GenAIComps/comps/dataprep/redis/langchain`, then the test script name should be `GenAIComps/tests/test_dataprep_redis_langchain.sh`. - - If the PR introduces new example for `GenAIExamples`, the PR must include new example end to end tests. The test script name should match with the example name so the test will be automatically triggered by test structure, for examples, if the example is `GenAIExamples/ChatQnA`, then the test script name should be `ChatQnA/tests/test_chatqna_on_gaudi.sh` and `ChatQnA/tests/test_chatqna_on_xeon.sh`. - -Pull Request Review -################### -You can add reviewers from [the code owners list](../codeowner.md) to your PR. - - -.. _OPEA Project Issues: https://github.com/search?q=org%3Aopea-project+%2Fissues&type=issues - -.. _open pull requests: https://github.com/opea-project/GenAIComps/pulls - -.. _OPEA Technical Discuss: mailing list: https://lists.lfaidata.foundation/g/OPEA-technical-discuss - - -Before starting on a patch, first check in our issues `OPEA Project Issues`_ -system to see what's been reported on the issue you'd like to address. Have a -conversation on the `OPEA Technical Discuss` to see what others think of your issue (and proposed solution). You -may find others that have encountered the issue you're finding, or that have -similar ideas for changes or additions. Send a message to the `OPEA Technical Discuss`_ to introduce and discuss your idea with the development -community. - -It's always a good practice to search for existing or related issues before -submitting your own. When you submit an issue (bug or feature request), the -triage team will review and comment on the submission, typically within a few -business days. - -You can find all `open pull requests`_ on GitHub and open `OPEA Project Issues`_ in Github issues. - - -### Reporting Issues - -If OPEA user runs into some unexpected behavior, reporting the issue to the `Issues` page under the corresponding github project is the proper way to do. Please ensure there is no similar one already existing on the issue list). Please follow the Bug Report template and supply as much information as you can, and any additional insights you might have. It's helpful if the issue submitter can narrow down the problematic behavior to a minimal reproducible test case. - - -.. _git_setup: - -Git Setup -********* - -We need to know who you are, and how to contact you. To add this -information to your Git installation, set the Git configuration -variables ``user.name`` to your full name, and ``user.email`` to your -email address. - -For example, if your name is ``OPEA Developer`` and your email -address is ``opea.developer@example.com``: - -.. code-block:: console - - git config --global user.name "OPEA Developer" - git config --global user.email "opea.developer@example.com" - - -Pull Request Guidelines -*********************** -When opening a new Pull Request, adhere to the following guidelines to ensure -compliance with OPEA standards and facilitate the review process. - -If in doubt, it's advisable to explore existing Pull Requests within the OPEA -repository. Use the search filters and labels to locate PRs related to changes -similar to the ones you are proposing. - -.. _commit-guidelines: - -Commit Message Guidelines -========================= - -Changes are submitted as Git commits. Each commit has a *commit -message* describing the change. Acceptable commit messages look like -this: - -.. code-block:: none - - [area]: [summary of change] - - [Commit message body (must be non-empty)] - - Signed-off-by: [Your Full Name] <[your.email@address]> - -You need to change text in square brackets (``[like this]``) above to -fit your commit. - -Examples and more details follow. - -Example -------- - -Here is an example of a good commit message. - -.. code-block:: none - - drivers: sensor: abcd1234: fix bus I/O error handling - - The abcd1234 sensor driver is failing to check the flags field in - the response packet from the device which signals that an error - occurred. This can lead to reading invalid data from the response - buffer. Fix it by checking the flag and adding an error path. - - Signed-off-by: OPEA Developer - -[area]: [summary of change] ---------------------------- - -This line is called the commit's *title*. Titles must be: - -* one line -* less than 72 characters long -* followed by a completely blank line - -[area] - The ``[area]`` prefix usually identifies the area of code - being changed. It can also identify the change's wider - context if multiple areas are affected. - - Here are some examples: - - * ``doc: ...`` for documentation changes - * ``drivers: foo:`` for ``foo`` driver changes - * ``Bluetooth: Shell:`` for changes to the Bluetooth shell - * ``net: ethernet:`` for Ethernet-related networking changes - * ``dts:`` for treewide devicetree changes - * ``style:`` for code style changes - - If you're not sure what to use, try running ``git log FILE``, where - ``FILE`` is a file you are changing, and using previous commits that - changed the same file as inspiration. - -[summary of change] - The ``[summary of change]`` part should be a quick description of - what you've done. Here are some examples: - - * ``doc: update wiki references to new site`` - * ``drivers: sensor: sensor_shell: fix channel name collision`` - -Commit Message Body -------------------- - -.. warning:: - - An empty commit message body is not permitted. Even for trivial - changes, please include a descriptive commit message body. Your - pull request will fail CI checks if you do not. - -This part of the commit should explain what your change does, and why -it's needed. Be specific. A body that says ``"Fixes stuff"`` will be -rejected. Be sure to include the following as relevant: - -* **what** the change does, -* **why** you chose that approach, -* **what** assumptions were made, and -* **how** you know it works -- for example, which tests you ran. - -Each line in your commit message should usually be 75 characters or -less. Use newlines to wrap longer lines. Exceptions include lines -with long URLs, email addresses, etc. - -For examples of accepted commit messages, you can refer to the OPEA GitHub -`changelog `__. - - -Signed-off-by: ... ------------------- - -.. tip:: - - You should have set your :ref:`git_setup` - already. Create your commit with ``git commit -s`` to add the - Signed-off-by: line automatically using this information. - -For open source licensing reasons, your commit must include a -Signed-off-by: line that looks like this: - -.. code-block:: none - - Signed-off-by: [Your Full Name] <[your.email@address]> - -For example, if your full name is ``OPEA Developer`` and your email -address is ``opea.developer@example.com``: - -.. code-block:: none - - Signed-off-by: OPEA Developer - -This means that you have personally made sure your change complies -with the :ref:`DCO`. For this reason, you must use your legal name. -Pseudonyms or "hacker aliases" are not permitted. - -Your name and the email address you use must match the name and email -in the Git commit's ``Author:`` field. - -See the :ref:`contributor-expectations` for a more complete discussion of -contributor and reviewer expectations. - -Adding links ------------- - -.. _GitHub references: - https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls - -Do not include `GitHub references`_ in the commit message directly, as it can -lose meaning in case the repository is forked, for example. Instead, if the -change addresses a specific GitHub issue, include in the Pull Request message a -line of the form: - -.. code-block:: none - - Fixes #[issue number] - -Where ``[issue number]`` is the relevant GitHub issue's number. For -example: - -.. code-block:: none - - Fixes: #1234 - -You can point to other relevant information that can be found on the web using -:code:`Link:` tags. This includes, for example: GitHub issues, datasheets, -reference manuals, etc. - -.. code-block:: none - - Link: https://github.com/opea-project/genAIComps/issues - -.. _coding_style: - -Coding Style -============ - -.. _Linux kernel coding style: - https://kernel.org/doc/html/latest/process/coding-style.html - -In general, follow the `Linux kernel coding style`_, with the following -exceptions: - -* The line length is 100 columns or fewer. In the documentation, longer lines - for URL references are an allowed exception. -* Add braces to every ``if``, ``else``, ``do``, ``while``, ``for`` and - ``switch`` body, even for single-line code blocks. Use the ``--ignore BRACES`` - flag to make *checkpatch* stop complaining. -* Use spaces instead of tabs to align comments after declarations, as needed. -* Use C89-style single line comments, ``/* */``. The C99-style single line - comment, ``//``, is not allowed. -* Use ``/** */`` for doxygen comments that need to appear in the documentation. -* Avoid using binary literals (constants starting with ``0b``). -* Avoid using non-ASCII symbols in code, unless it significantly improves - clarity, avoid emojis in any case. - -Use these coding guidelines to ensure that your development complies with the -project's style and naming conventions. - -The Linux kernel GPL-licensed tool ``checkpatch`` is used to check -coding style conformity. - -.. note:: - checkpatch does not currently run on Windows. - -Checkpatch is available in the scripts directory. To invoke it when committing -code, make the file *$OPEA_BASE/.git/hooks/pre-commit* executable and edit -it to contain: - -.. code-block:: bash - - #!/bin/sh - set -e exec - exec git diff --cached | ${OPEA_BASE}/scripts/checkpatch.pl - - -Instead of running checkpatch at each commit, you may prefer to run it only -before pushing on OPEA repo. To do this, make the file -*$OPEA_BASE/.git/hooks/pre-push* executable and edit it to contain: - -.. code-block:: bash - - #!/bin/sh - remote="$1" - url="$2" - - z40=0000000000000000000000000000000000000000 - - echo "Run push hook" - - while read local_ref local_sha remote_ref remote_sha - do - args="$remote $url $local_ref $local_sha $remote_ref $remote_sha" - exec ${OPEA_BASE}/scripts/series-push-hook.sh $args - done - - exit 0 - -If you want to override checkpatch verdict and push you branch despite reported -issues, you can add option --no-verify to the git push command. - -A more complete alternative to this is using :ref:`check_compliance_py` script. - -clang-format ------------- - -The `clang-format tool `_ can -be helpful to quickly reformat large amounts of new source code to our -`Coding Style`_ standards together with the ``.clang-format`` configuration file -provided in the repository. ``clang-format`` is well integrated into most -editors, but you can also run it manually like this: - -.. code-block:: bash - - clang-format -i my_source_file.c - -``clang-format`` is part of LLVM, which can be downloaded from the project -`releases page `_. Note that if -you are a Linux user, ``clang-format`` will likely be available as a package in -your distribution repositories. - -When there are differences between the `Coding Style`_ guidelines and the -formatting generated by code formatting tools, the `Coding Style`_ guidelines -take precedence. If there is ambiguity between formatting tools and the -guidelines, maintainers may decide which style should be adopted. - -.. _Continuous Integration: - -Continuous Integration (CI) -=========================== - -The OPEA Project operates a Continuous Integration (CI) system that runs on -every Pull Request (PR) in order to verify several aspects of the PR: - -* Git commit formatting -* Coding Style -* Twister builds for multiple architectures and boards -* Documentation build to verify any doc changes - -CI is run on Github Actions and it uses the same tools described in the -`CI Tests`_ section. The CI results must be green indicating "All -checks have passed" before the Pull Request can be merged. CI is run when the -PR is created, and again every time the PR is modified with a commit. - -The current status of the CI run can always be found at the bottom of the -GitHub PR page, below the review status. Depending on the success or failure -of the run you will see: - -* "All checks have passed" -* "All checks have failed" - -In case of failure you can click on the "Details" link presented below the -failure message in order to navigate to ``Github Actions`` and inspect the -results. -Once you click on the link you will be taken to the ``Github actions`` summary -results page where a table with all the different builds will be shown. To see -what build or test failed click on the row that contains the failed (i.e. -non-green) build. - -.. _CI Tests: - -Running CI Tests Locally -======================== - -.. _check_compliance_py: - -check_compliance.py -------------------- - -The ``check_compliance.py`` script serves as a valuable tool for assessing code -compliance with OPEA's established guidelines and best practices. The script -acts as wrapper for a suite of tools that performs various checks, including -linters and formatters. - -Developers are encouraged to run the script locally to validate their changes -before opening a new Pull Request: - -.. code-block:: bash - - ./scripts/ci/check_compliance.py -c upstream/main.. - -twister -------- - -.. note:: - twister is only fully supported on Linux; on Windows and MacOS the execution - of tests is not supported, only building. - -If you think your change may break some test, you can submit your PR as a draft -and let the project CI automatically run the :ref:`twister_script` for you. - -If a test fails, you can check from the CI run logs how to rerun it locally, -for example: - -.. code-block:: bash - - west twister -p native_sim -s tests/drivers/build_all/sensor/sensors.generic_test - -.. _static_analysis: - -Static Code Analysis -******************** - -Coverity Scan is a free service for static code analysis of Open Source -projects. It is based on Coverity's commercial product and is able to analyze -C, C++ and Java code. - -Coverity's static code analysis doesn't run the code. Instead of that it uses -abstract interpretation to gain information about the code's control flow and -data flow. It's able to follow all possible code paths that a program may take. -For example the analyzer understands that malloc() returns a memory that must -be freed with free() later. It follows all branches and function calls to see -if all possible combinations free the memory. The analyzer is able to detect -all sorts of issues like resource leaks (memory, file descriptors), NULL -dereferencing, use after free, unchecked return values, dead code, buffer -overflows, integer overflows, uninitialized variables, and many more. - -The results are available on the `Coverity Scan -`_ website. In order to access the -results you have to create an account yourself. From the OPEA project page, -you may select "Add me to project" to be added to the project. New members must -be approved by an admin. - -Static analysis of the OPEA codebase is conducted on a bi-weekly basis. GitHub -issues are automatically created for any issues detected by static analysis -tools. These issues will have the same (or equivalent) priority initially -defined by the tool. - -To ensure accountability and efficient issue resolution, they are assigned to -the respective maintainer who is responsible for the affected code. - -A dedicated team comprising members with expertise in static analysis, code -quality, and software security ensures the effectiveness of the static -analysis process and verifies that identified issues are properly -triaged and resolved in a timely manner. - -Workflow -======== - -If after analyzing the Coverity report it is concluded that it is a false -positive please set the classification to either "False positive" or -"Intentional", the action to "Ignore", owner to your own account and add a -comment why the issue is considered false positive or intentional. - -Update the related Github issue in the OPEA project with the details, and only close -it after completing the steps above on scan service website. Any issues -closed without a fix or without ignoring the entry in the scan service will be -automatically reopened if the issue continues to be present in the code. - -.. _Contribution workflow: - -Contribution Workflow -********************* - -One general practice we encourage, is to make small, -controlled changes. This practice simplifies review, makes merging and -rebasing easier, and keeps the change history clear and clean. - -When contributing to the OPEA Project, it is also important you provide as much -information as you can about your change, update appropriate documentation, -and test your changes thoroughly before submitting. - -The general GitHub workflow used by OPEA developers uses a combination of -command line Git commands and browser interaction with GitHub. As it is with -Git, there are multiple ways of getting a task done. We'll describe a typical -workflow here: - -.. _Create a Fork of OPEA: - https://github.com/opea-project#fork-destination-box - -#. `Create a Fork of OPEA`_ - to your personal account on GitHub. (Click on the fork button in the top - right corner of the OPEA project repo page in GitHub.) - -#. On your development computer, change into the :file:`OPEA` folder that was - created when you :ref:`obtained the code `:: - - cd opea-project - - Rename the default remote pointing to the `upstream repository - `_ from ``origin`` to - ``upstream``:: - - git remote rename origin upstream - - Let Git know about the fork you just created, naming it ``origin``:: - - git remote add origin https://github.com//opea-project - - and verify the remote repos:: - - git remote -v - - The output should look similar to:: - - origin https://github.com//opea-project (fetch) - origin https://github.com//opea-project (push) - upstream https://github.com/opea-project (fetch) - upstream https://github.com/opea-project(push) - -#. Create a topic branch (off of ``main``) for your work (if you're addressing - an issue, we suggest including the issue number in the branch name):: - - git checkout main - git checkout -b fix_comment_typo - - Some OPEA subsystems do development work on a separate branch from - ``main`` so you may need to indicate this in your checkout:: - - git checkout -b fix_out_of_date_patch origin/net - -#. Make changes, test locally, change, test, test again, ... (Check out the - prior chapter on `twister`_ as well). - -#. When things look good, start the pull request process by adding your changed - files:: - - git add [file(s) that changed, add -p if you want to be more specific] - - You can see files that are not yet staged using:: - - git status - -#. Verify changes to be committed look as you expected:: - - git diff --cached - -#. Commit your changes to your local repo:: - - git commit -s - - The ``-s`` option automatically adds your ``Signed-off-by:`` to your commit - message. Your commit will be rejected without this line that indicates your - agreement with the :ref:`DCO`. See the :ref:`commit-guidelines` section for - specific guidelines for writing your commit messages. - -#. Push your topic branch with your changes to your fork in your personal - GitHub account:: - - git push origin fix_comment_typo - -#. In your web browser, go to your forked repo and click on the - ``Compare & pull request`` button for the branch you just worked on and - you want to open a pull request with. - -#. Review the pull request changes, and verify that you are opening a pull - request for the ``main`` branch. The title and message from your commit - message should appear as well. - -#. A bot will assign one or more suggested reviewers (based on the - MAINTAINERS file in the repo). If you are a project member, you can - select additional reviewers now too. - -#. Click on the submit button and your pull request is sent and awaits - review. Email will be sent as review comments are made, or you can check - on your pull request at https://github.com/opea-project/pulls. - - .. note:: As more commits are merged upstream, the GitHub PR page will show - a ``This branch is out-of-date with the base branch`` message and a - ``Update branch`` button on the PR page. That message should be ignored, - as the commits will be rebased as part of merging anyway, and triggering - a branch update from the GitHub UI will cause the PR approvals to be - dropped. - -#. While you're waiting for your pull request to be accepted and merged, you - can create another branch to work on another issue. (Be sure to make your - new branch off of ``main`` and not the previous branch.):: - - git checkout main - git checkout -b fix_another_issue - - and use the same process described above to work on this new topic branch. - -#. If reviewers do request changes to your patch, you can interactively rebase - commit(s) to fix review issues. In your development repo:: - - git rebase -i ^ - - In the interactive rebase editor, replace ``pick`` with ``edit`` to select - a specific commit (if there's more than one in your pull request), or - remove the line to delete a commit entirely. Then edit files to fix the - issues in the review. - - As before, inspect and test your changes. When ready, continue the - patch submission:: - - git add [file(s)] - git rebase --continue - - Update commit comment if needed, and continue:: - - git push --force origin fix_comment_typo - - By force pushing your update, your original pull request will be updated - with your changes so you won't need to resubmit the pull request. - -#. After pushing the requested change, check on the PR page if there is a - merge conflict. If so, rebase your local branch:: - - git fetch --all - git rebase --ignore-whitespace upstream/main - - The ``--ignore-whitespace`` option stops ``git apply`` (called by rebase) - from changing any whitespace. Resolve the conflicts and push again:: - - git push --force origin fix_comment_typo - - .. note:: While amending commits and force pushing is a common review model - outside GitHub, and the one recommended by OPEA, it's not the main - model supported by GitHub. Forced pushes can cause unexpected behavior, - such as not being able to use "View Changes" buttons except for the last - one - GitHub complains it can't find older commits. You're also not - always able to compare the latest reviewed version with the latest - submitted version. When rewriting history GitHub only guarantees access - to the latest version. - -#. If the CI run fails, you will need to make changes to your code in order - to fix the issues and amend your commits by rebasing as described above. - Additional information about the CI system can be found in - `Continuous Integration`_. - -.. _contribution_tips: - -Contribution Tips -================= - -The following is a list of tips to improve and accelerate the review process of -Pull Requests. If you follow them, chances are your pull request will get the -attention needed and it will be ready for merge sooner than later: - -.. _git-rebase: - https://git-scm.com/docs/git-rebase#Documentation/git-rebase.txt---keep-base - -#. When pushing follow-up changes, use the ``--keep-base`` option of - `git-rebase`_ - -#. On the PR page, check if the change can still be merged with no merge - conflicts - -#. Make sure title of PR explains what is being fixed or added - -#. Make sure your PR has a body with more details about the content of your - submission - -#. Make sure you reference the issue you are fixing in the body of the PR - -#. Watch early CI results immediately after submissions and fix issues as they - are discovered - -#. Revisit PR after 1-2 hours to see the status of all CI checks, make sure all - is green - -#. If you get request for changes and submit a change to address them, make - sure you click the "Re-request review" button on the GitHub UI to notify - those who asked for the changes - - - -Identifying Contribution Origin -=============================== - -When adding a new file to the tree, it is important to detail the source of -origin on the file, provide attributions, and detail the intended usage. In -cases where the file is an original to OPEA, the commit message should -include the following ("Original" is the assumption if no Origin tag is -present):: - - Origin: Original - -In cases where the file is :ref:`imported from an external project -`, the commit message shall contain details regarding -the original project, the location of the project, the SHA-id of the origin -commit for the file and the intended purpose. - -For example, a copy of a locally maintained import:: - - Origin: Contiki OS - License: BSD 3-Clause - URL: http://www.contiki-os.org/ - commit: 853207acfdc6549b10eb3e44504b1a75ae1ad63a - Purpose: of networking stack. - -For example, a copy of an externally maintained import in a module repository:: - - Origin: Tiny Crypt - License: BSD 3-Clause - URL: https://github.com/01org/tinycrypt - commit: 08ded7f21529c39e5133688ffb93a9d0c94e5c6e - Purpose: of TinyCrypt - - - - - diff --git a/developer-guides/doc_guidelines.rst b/developer-guides/doc_guidelines.rst index 1aab7838..780bbab8 100644 --- a/developer-guides/doc_guidelines.rst +++ b/developer-guides/doc_guidelines.rst @@ -34,6 +34,12 @@ with MyST and Sphinx-defined directives and roles used to create the documentati you're reading. It also provides best-known-methods for working with a mixture of reStructuredText and markdown. +.. rst-class:: rst-columns + +.. contents:: + :local: + :depth: 1 + Markdown vs. RestructuredText ***************************** @@ -652,6 +658,7 @@ We've kept the substitutions list small but you can add others as needed by submitting a change to the ``substitutions.txt`` file. Include Content from Other Files +******************************** You can directly incorporate a document fragment from another file into your reST or markdown content by using an ``include`` directive. @@ -701,6 +708,18 @@ markdown content by using an ``include`` directive. These and other options described in the `docutils include directive `_ documentation. + As a practical example, here's how you could include markdown content into + a reST document, and have that included content interpreted as markdown. + Note that Sphinx will complain if it finds a .md or .rst file that's not + included in a toctree directive, it's bese to us a .txt extension for + included files:: + + .. include:: mdtable.txt + :parser: myst_parser.sphinx_ + + That's how we showed how a more free-form markdown table syntax would be + rendered in another part of this document. + .. group-tab:: markdown MyST directives can be used to incorporate content from another file @@ -848,7 +867,10 @@ Code and Command Examples "age": 25 } - TODO: add the list of supported languages. + Commonly used languages are: ``bash``, ``console``, ``none``, ``json``, + ``python``, ``markdown``, and ``rest``. See this + `complete list of Pygments lexer languages `_ + for more (use the "Short name" shown). Images ****** @@ -993,78 +1015,126 @@ Drawings Alternative Tabbed Content ************************** -In reST, instead of creating multiple documents with common material except for some -specific sections, you can write one document and provide alternative content -to the reader via a tabbed interface. When the reader clicks a tab, the -content for that tab is displayed. For example:: +.. tabs:: + + .. group-tab:: reST - .. tabs:: + In reST, instead of creating multiple documents with common material except for some + specific sections, you can write one document and provide alternative content + to the reader via a tabbed interface. When the reader clicks a tab, the + content for that tab is displayed. For example:: - .. tab:: Apples + .. tabs:: - Apples are green, or sometimes red. + .. tab:: Apples - .. tab:: Pears + Apples are green, or sometimes red. - Pears are green. + .. tab:: Pears - .. tab:: Oranges + Pears are green. - Oranges are orange. + .. tab:: Oranges -will display as: + Oranges are orange. -.. tabs:: + will display as: - .. tab:: Apples + .. tabs:: - Apples are green, or sometimes red. + .. tab:: Apples - .. tab:: Pears + Apples are green, or sometimes red. - Pears are green. + .. tab:: Pears - .. tab:: Oranges + Pears are green. - Oranges are orange. + .. tab:: Oranges -Tabs can also be grouped so that changing the current tab in one area -changes all tabs with the same name throughout the page. For example: + Oranges are orange. -.. tabs:: + Tabs can also be grouped so that changing the current tab in one area + changes all tabs with the same name throughout the page. For example: - .. group-tab:: Linux + .. tabs:: - Linux Line 1 + .. group-tab:: Linux - .. group-tab:: macOS + Linux Line 1 - macOS Line 1 + .. group-tab:: macOS - .. group-tab:: Windows + macOS Line 1 - Windows Line 1 + .. group-tab:: Windows -.. tabs:: + Windows Line 1 + + .. tabs:: + + .. group-tab:: Linux - .. group-tab:: Linux + Linux Line 2 - Linux Line 2 + .. group-tab:: macOS - .. group-tab:: macOS + macOS Line 2 - macOS Line 2 + .. group-tab:: Windows - .. group-tab:: Windows + Windows Line 2 - Windows Line 2 + In this latter case, we're using a ``.. group-tab::`` directive instead of + a ``.. tab::`` directive. Under the hood, we're using the `sphinx-tabs + `_ extension that's included + in the OPEA docs (requirements.txt) setup. Within a tab, you can have most + any content *other than a heading* (code-blocks, ordered and unordered + lists, pictures, paragraphs, and such). + + .. group-tab:: markdown + + While markdown does not have native support for tabbed alternatives, we do + support this in the OPEA markdown documentation with the Myst Parser + extension:: + + ::::{tab-set} + + :::{tab-item} Linux + :sync: Linux + + This content will show on the Linux tab + ::: + :::{tab-item} macOS + :sync: macOS + + This content will show on the macOS tab + ::: + :::{tab-item} Windows + :sync: Windows + + This content will show on the Windows tab + ::: + :::: + + Each ``tab-set`` used a ``tab-item`` for each tabbed alternative. Adding + the ``:sync: `` option causes all ``tab-set`` that share that + ``tab-item`` name to be synchronized through the document (all the tabs + will change to the selected tab). + + Note the use of three colons as the fence instead of the normal use of + three backticks. This allows use of three backtics within a tab for + denoting a code block. Also note how nested colon fences are used with + four colons for the ``tab-set``, and that each colon + fence must be terminated with a matching colon fence because indenting is + not used for content within the fenced area (normal for markdown). + + Here's what that would look like with two sets of tabbed alternative + content: + + .. include:: tabbed-alternative.txt + :parser: myst_parser.sphinx_ -In this latter case, we're using a ``.. group-tab::`` directive instead of -a ``.. tab::`` directive. Under the hood, we're using the `sphinx-tabs -`_ extension that's included -in the OPEA docs (requirements.txt) setup. Within a tab, you can have most -any content *other than a heading* (code-blocks, ordered and unordered -lists, pictures, paragraphs, and such). Instruction Steps ***************** diff --git a/developer-guides/docbuild.rst b/developer-guides/docbuild.rst index dffdf0fe..f93b57f3 100644 --- a/developer-guides/docbuild.rst +++ b/developer-guides/docbuild.rst @@ -7,6 +7,8 @@ These instructions walk you through generating the OPEA project documentation and publishing it to https://opea-project.github.io. You can also use these instructions to generate the OPEA documentation on your local system. +.. rst-class:: rst-columns + .. contents:: :local: :depth: 1 @@ -61,6 +63,11 @@ Some content is manipulated or generated during the doc build process: self-updated when new microservices are added to the GenAIComps/comps directory. +- The CODEOWNERS files in the repos, containing the list of responsible + reviewers for those repos, are processed into a nice looking table included in + the ``community/codeowners.md`` document. That way the list of project code + owners is kept in sync with what's in the CODEOWNERS files used by GitHub. + - References in markdown files to markdown files (.md file extension) are converted to the corresponding generated HTML files by Sphinx using the Myst and sphinx-md extensions. diff --git a/developer-guides/index.rst b/developer-guides/index.rst index 2b9ee21f..ab6cdcf7 100644 --- a/developer-guides/index.rst +++ b/developer-guides/index.rst @@ -17,7 +17,6 @@ Documentation Guides ******************** .. toctree:: - :maxdepth: 1 doc_guidelines graphviz diff --git a/developer-guides/tabbed-alternative.txt b/developer-guides/tabbed-alternative.txt new file mode 100644 index 00000000..7451c87b --- /dev/null +++ b/developer-guides/tabbed-alternative.txt @@ -0,0 +1,43 @@ +Here's an example of markdown with two tab sets that are synchronized when +chosen by the viewer: + +::::{tab-set} + +:::{tab-item} Linux +:sync: Linux + +This content will show on the Linux tab +::: +:::{tab-item} macOS +:sync: macOS + +This content will show on the macOS tab +::: +:::{tab-item} Windows +:sync: Windows + +This content will show on the Windows tab +::: +:::: + +Some more content here followed by another tab set: + +::::{tab-set} + +:::{tab-item} Linux +:sync: Linux + +This is more content that will show on this Linux tab +::: +:::{tab-item} macOS +:sync: macOS + +This is more content that will show on this macOS tab +::: +:::{tab-item} Windows +:sync: Windows + +This is more content that will show on this Windows tab +::: +:::: + diff --git a/scripts/sync-all-repos.sh b/scripts/sync-all-repos.sh new file mode 100755 index 00000000..9d53afdf --- /dev/null +++ b/scripts/sync-all-repos.sh @@ -0,0 +1,18 @@ +#!/bin/bash + +# synch local copy and origin with what's in upstream repo +# assumes there's an origin and upstream remote defined in each of the repos + +# optionally, you can give a branch name as a first parameter and it will +# checkout and sync all the repos to that branchname + +branch=${1:-main} + +for d in GenAIComps GenAIExamples GenAIEval GenAIInfra docs opea-project.github.io ; do + cd ~/opea-project/"$d" + echo "====" $d + git checkout $branch + git fetch upstream + git merge upstream/$branch + git push origin $branch +done diff --git a/sphinx/_static/opea-custom.css b/sphinx/_static/opea-custom.css index 4dc79c08..ab2374ac 100644 --- a/sphinx/_static/opea-custom.css +++ b/sphinx/_static/opea-custom.css @@ -1,17 +1,18 @@ /* -- Extra CSS styles for OPEA content (RTD theme) ----------------------- */ -/* make the page width fill the window */ +/* make the page width use more of the availalbe window */ .wy-nav-content { max-width: 1100px; } -/* (temporarily) add an under development tagline to the bread crumb) */ +/* (temporarily) add an under development tagline to the bread crumb .wy-breadcrumbs::after { content: " (Content is under construction)"; background-color: #FFFACD; color: red; font-weight: bold; } +*/ /* pygments tweak for white-on-black console */ @@ -92,7 +93,6 @@ div:not(.admonition) > p + ul, div:not(.admonition) > p + ol { /* add some space before the figure caption */ p.caption { -# border-top: 1px solid; margin-top: 1em; } @@ -123,7 +123,7 @@ table { text-align: center; } -/* make .. hlist:: tables fill the page */ +/* make .. hlist:: tables fill the page (not really used) */ table.hlist { width: 95% !important; } @@ -216,15 +216,6 @@ kbd font-size: 1.1rem; } -/* tweek for images in the home-page grid */ - -/* -.grid-item img { - /* max-width: 50%; - max-height: 50%; - margin-bottom: 0.7rem; -} */ - .grid-item a:hover { background-color: #FFB500; @@ -249,6 +240,7 @@ kbd /* add a class for multi-column support * in docs to replace use of .hlist with * a .. rst-class:: rst-columns + * default is 3 columns but you can choose 2 */ .rst-columns2 { @@ -262,7 +254,7 @@ kbd margin-bottom: 1em; } -/* numbered "h2" steps */ +/* numbered "h2" steps with an outdented big grey circle */ body { counter-reset: step-count; @@ -290,7 +282,9 @@ section.numbered-step h2::before { font-weight: bold; } -/* add icon on external links */ +/* add icon on external links, I sometimes have second thoughts about this. + * it makes it easy to see which links are internal vs. external, but it + * sometimes looks messy. */ a.reference.external::after { font-family: 'FontAwesome'; font-size: 80%;