General maintenance fo documentation and development lifecycle#364
Merged
General maintenance fo documentation and development lifecycle#364
Conversation
Collaborator
Stell0
commented
Mar 26, 2026
Stell0
commented
- Add AGENTS.md and STRUCTURE.md for agentic development
- Improve local testing workflow
- Update documentation
Add a repo-local Bats harness that generates its own Tancredi configuration, writable runtime tree, and PHP server entrypoint. This lets developers run the end-to-end suite without relying on an existing Apache deployment or root-owned CI paths. Keep the Apache-based CI layout available through ./test/run.sh system, update the workflow to call it explicitly, and parameterize the Bats helpers and fixtures so both modes share the same suite. Document the new local and system test paths in test/README.md and AGENTS.md, and make /check/ping respect the tancredi_conf override used by the local harness.
Update the docs to match the current Tancredi runtime and API behavior. Document the provisioning flow in more detail, including the tok1/tok2 security model, tokenless bootstrap handling, protected asset delivery, and runtime variables. Refresh the installation, API, auth, templates, and index pages to reflect the current PHP 8.1+/Slim 4 stack and public paths. Exclude local Bundler directories from the Jekyll source tree so documentation builds do not break when gems are installed locally.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR modernizes the repo’s developer experience and documentation, with a focus on making the Bats E2E suite easier to run locally while keeping CI/system-layout compatibility.
Changes:
- Reworked
test/run.shto support a default “local” harness (generated config + repo-local writable runtime + PHP built-in server) and an explicit “system” mode for CI/deployed layouts. - Updated Bats helpers/tests to respect environment-configurable paths and to write artifacts to a configurable directory.
- Refreshed and expanded Jekyll docs (installation, API, templates, provisioning flow) and added contributor-facing repo guides (
AGENTS.md,STRUCTURE.md).
Reviewed changes
Copilot reviewed 19 out of 20 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
test/run.sh |
Adds local/system modes, generates config/runtime layout, starts PHP built-in server in local mode. |
test/router.php |
New router for PHP built-in server to dispatch to public/api-v1.php and public/provisioning.php. |
test/bats/tancredi_client.bash |
Centralizes path configuration and artifact handling for Bats tests. |
test/bats/50_template_rendering.bats |
Uses configurable template override dir instead of hard-coded paths. |
test/bats/10_models.bats |
Uses new reset helper instead of deleting /var/lib/tancredi directly. |
test/bats/05_upgrade.bats |
Uses helper paths for scopes and upgrade script; updates a test name. |
test/README.md |
Documents local vs system/CI test execution and troubleshooting. |
public/provisioning.php |
/check/ping now reads config mtime from tancredi_conf env var when set. |
docs/templates.md |
Updates template/runtime filter docs and precedence order. |
docs/provisioning.md |
New provisioning flow + security documentation page. |
docs/paths.md |
Adds docs link for tok1 rotation endpoint. |
docs/installation.md |
Updates stack requirements and installation/configuration guidance. |
docs/index.md |
Updates high-level product and flow overview. |
docs/auth.md |
Updates auth middleware example for Slim 4 / PSR-15. |
docs/_config.yml |
Updates Jekyll exclude list and adds additional config. |
docs/API.md |
Refreshes API overview, inheritance, auth, and write restrictions docs. |
STRUCTURE.md |
New repository structure guide. |
AGENTS.md |
New agentic-dev guidance and repo conventions/invariants. |
.gitignore |
Ignores var/test-runtime/. |
.github/workflows/bats.yml |
Runs ./test/run.sh system explicitly in CI. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
#365) * Initial plan * fix(test): normalize *_dir vars to always end with trailing slash Each *_dir variable is now normalized immediately after assignment using the `${var%/}/` pattern. This ensures that overriding TANCREDI_RW_DIR, TANCREDI_RO_DIR, TANCREDI_SCRIPTS_DIR, or TANCREDI_TEMPLATE_CUSTOM_DIR without a trailing slash still yields correct subdirectory paths. Also remove the overly-restrictive prefix check in tancredi_reset_rw_dir that limited deletion to /var/lib/tancredi/*, which blocked local test mode where TANCREDI_RW_DIR points to a test-runtime directory. The empty/root guard remains. Co-authored-by: Stell0 <4547897+Stell0@users.noreply.github.com> Agent-Logs-Url: https://github.com/nethesis/tancredi/sessions/7890c6d0-cae1-44a9-8ac9-b4b59bb546d6 --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Stell0 <4547897+Stell0@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.