diff --git a/developer_manual/architecture.rst b/developer_manual/architecture.rst new file mode 100644 index 0000000..9be3de2 --- /dev/null +++ b/developer_manual/architecture.rst @@ -0,0 +1,88 @@ +.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors +.. SPDX-License-Identifier: CC-BY-3.0 + +Architecture and code map +========================= + +LibreSign is a Nextcloud application. This page is the canonical starting point +for understanding where responsibilities live before changing code. + +Use the application repository as the source of truth for current class names, +APIs and implementation details: + +`LibreSign/libresign `_. + +Repository map +-------------- + +The main application areas are: + +``lib/`` + PHP backend code. Controllers expose HTTP/OCS behavior, services contain + application logic and orchestration, database classes persist application + state, and handlers contain specialized signing/certificate behavior. + +``src/`` + Vue and TypeScript frontend code. + +``tests/php/`` + PHP unit tests. + +``tests/integration/`` + Integration scenarios and their support code. + +``src/tests/`` + Frontend unit tests. + +``playwright/`` + Browser/end-to-end test support where present in the current application + repository. + +``appinfo/`` + Nextcloud application metadata and route/configuration declarations. + +``3rdparty/`` + Scoped third-party dependencies. Follow the instructions in that directory + before changing it. + +Responsibility boundaries +------------------------- + +Backend enforcement +~~~~~~~~~~~~~~~~~~~ + +Permissions, validation, policy resolution and other security-sensitive +business rules must be enforced by the backend. Frontend checks may improve the +user experience, but they are not an authorization boundary. + +Generated and vendored content +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Do not edit generated translations, generated API/type output or vendored +dependencies as if they were normal source files. Change their source contract +and regenerate them using the workflow documented by the application +repository. + +Signing and document integrity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Changes affecting document signing, PDF validation, certificates, cryptographic +policy, authorization or persisted audit state require focused regression and +negative tests at the affected trust boundary. + +Nextcloud integration +~~~~~~~~~~~~~~~~~~~~~ + +Prefer public Nextcloud OCP APIs and the repository's existing integration +patterns. Before introducing a workaround for an upstream change, verify the +supported Nextcloud version and current upstream contract. + +Where to go next +---------------- + +- :doc:`getting-started/development-environment/index` for setting up a + development runtime. +- :doc:`getting-started/tests` for testing and validation. +- :doc:`development-workflow` for the normal issue-to-pull-request workflow. +- :doc:`api/index` for the public API. +- :doc:`release-process` for release operations. diff --git a/developer_manual/development-workflow.rst b/developer_manual/development-workflow.rst new file mode 100644 index 0000000..5756d8a --- /dev/null +++ b/developer_manual/development-workflow.rst @@ -0,0 +1,86 @@ +.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors +.. SPDX-License-Identifier: CC-BY-3.0 + +Development workflow +==================== + +This page describes the durable contribution workflow for LibreSign. Repository +instructions such as ``AGENTS.md`` may add operational constraints for a +particular tool, but they should point back to this documentation instead of +duplicating it. + +Choose and understand the work +------------------------------ + +Start from a GitHub issue whenever possible. Before implementing it: + +- verify that the issue still matches the current code; +- check for existing pull requests or duplicate work; +- identify acceptance criteria, exclusions and real prerequisites; +- keep unrelated improvements out of the same change. + +Large outcomes should be split into independently reviewable issues when useful. +Use blocking relationships only for real prerequisites. + +Prepare the environment +----------------------- + +Use the supported development environment described in +:doc:`getting-started/development-environment/index`. + +The environment implementation may evolve, but contributors should not need to +maintain multiple independent Nextcloud Docker topologies for the same project. + +Implement a focused change +-------------------------- + +Prefer the smallest coherent change that satisfies the issue. + +Follow the current application architecture and contribution rules from the +base branch. Avoid unrelated refactors, dependency upgrades and formatting +churn unless they are required for the requested outcome. + +Validate the behavior +--------------------- + +Use :doc:`getting-started/tests` to choose the relevant test path. + +Prefer a focused regression test that fails under the unwanted behavior when +practical. Run narrow checks first, then broaden according to the changed +surface and current CI requirements. + +Record which commands actually ran and which checks could not be run. A focused +test does not prove the whole project is green. + +Review the final diff +--------------------- + +Before opening a pull request: + +- inspect every changed file for unrelated changes; +- compare the result with the issue acceptance criteria; +- check error paths, permissions and compatibility where relevant; +- verify generated files and documentation when the changed contract requires + them. + +Commit and open the pull request +-------------------------------- + +Follow :doc:`getting-started/commits` for commit requirements and DCO. + +Keep the pull request focused and make validation evidence easy to review: +reference the issue, summarize material implementation choices, list checks that +actually ran and describe known limitations when relevant. + +A pull request remains subject to the repository's current review, CI and +branch policies. + +After review or CI feedback +--------------------------- + +Re-evaluate feedback against the latest branch state before changing code. +When CI fails, identify the causal failure before adding retries, sleeps, +dependency pins or suppressions. + +Follow-up work that is useful but not required for the current issue should be +tracked separately instead of expanding the pull request indefinitely. diff --git a/developer_manual/getting-started/index.rst b/developer_manual/getting-started/index.rst index 13fc87d..d45bdec 100644 --- a/developer_manual/getting-started/index.rst +++ b/developer_manual/getting-started/index.rst @@ -2,10 +2,13 @@ Getting started =============== +Use these pages for the practical setup and contribution prerequisites. For the +overall issue-to-pull-request process, see :doc:`../development-workflow`. + .. toctree:: :maxdepth: 2 branch-policies development-environment/index tests - commits \ No newline at end of file + commits diff --git a/developer_manual/index.rst b/developer_manual/index.rst index 65eacb4..a2eb422 100644 --- a/developer_manual/index.rst +++ b/developer_manual/index.rst @@ -3,32 +3,48 @@ Developer manual ================ -Thank you for your interest in contributing to LibreSign! - -There are many ways to help our project: - -- Write code or fix bugs -- Test and reproduce reported issues -- Improve the documentation -- Translate to other languages -- Share the security and privacy the word -- Give a ⭐ on `GitHub `_ - -If you want to go further, you can also support LibreSign through +Thank you for your interest in contributing to LibreSign. + +This manual is the canonical source for durable LibreSign developer knowledge. +Repository-local guidance may point here for architecture, environment, testing +and contribution workflows instead of duplicating those topics. + +Start here +---------- + +- :doc:`architecture` — understand the application boundaries and code map. +- :doc:`getting-started/development-environment/index` — prepare a development + runtime. +- :doc:`development-workflow` — follow work from an issue to a reviewed pull + request. +- :doc:`getting-started/tests` — choose and run the appropriate validation. +- :doc:`api/index` — work with the public API. +- :doc:`release-process` — maintain and publish releases. + +There are many ways to help the project: + +- Write code or fix bugs. +- Test and reproduce reported issues. +- Improve the documentation. +- Translate to other languages. +- Help improve security and privacy. +- Give LibreSign a star on + `GitHub `_. + +You can also support LibreSign through `GitHub Sponsors `_. -We provide professional support for companies as well. - -For services or partnerships, please `contact us `_. - -Here you will find all the documentation for developers. +For professional services or partnerships, +`contact us `_. .. toctree:: :maxdepth: 2 :hidden: prologue/index + architecture getting-started/index + development-workflow api/index translation requesting-features