Operational Workflows

Operational Workflows

Forsetti keeps repository source and GitHub Wiki content separate. The wiki is maintained directly in the wiki repository so rich diagrams, architecture maps, and hand-curated operational pages remain reviewable as their own surface.

Manual Wiki Maintenance

flowchart TD
    A["Clone or pull Forsetti-Framework-Mac-iOS.wiki"] --> B["Edit Markdown pages directly"]
    B --> C["Validate links and Mermaid blocks"]
    C --> D["Commit wiki changes"]
    D --> E["Push wiki master"]
    E --> F["Review rendered GitHub Wiki"]

Loading

Wiki repository:

git clone https://github.com/flynn33/Forsetti-Framework-Mac-iOS.wiki.git

Version and Release Workflow

flowchart TD
    PR["Pull request"] --> Title["Conventional PR title"]
    Title --> Version["pr-version.yml updates SemVer files unless chore"]
    Version --> Checks["Guardrails and title lint"]
    Checks --> Merge["Merge to main"]
    Merge --> Release["Post-merge release process"]
    Release --> ReleaseOutputs["Tag, changelog, and GitHub release when applicable"]
    Release --> Docs["Review README and wiki for user-facing changes"]

Loading

Release automation does not update or publish the wiki. Wiki updates are intentional documentation changes that are committed directly to the wiki repository. For detailed version bump rules, see Versioning and Releases.

When wiki pages change, regenerate the tracked archive in the main repository:

git -C /path/to/Forsetti-Framework-Mac-iOS.wiki archive \
  --format=zip \
  --output=/path/to/Forsetti-Framework-Mac-iOS/docs/wiki/Forsetti-Framework-Mac-iOS-wiki-pages.zip \
  --prefix=Forsetti-Framework-Mac-iOS-wiki/ \
  HEAD

Version Update Checklist

File	Expected Update
Sources/ForsettiCore/ForsettiVersion.swift	Runtime version constant.
version.txt	Plain version value.
.release-please-manifest.json	Retained release configuration state; not changed by PR version automation.
README.md	Visible version and release links.
CHANGELOG.md	User-facing changes when a release PR is prepared.
Wiki pages	Manual update only when architecture, API, workflows, or integration guidance changes.
docs/wiki/Forsetti-Framework-Mac-iOS-wiki-pages.zip	Regenerated after wiki page changes so the repository archive mirrors the published wiki.

Consumer Integration Workflow

flowchart TD
    A["Add package dependency"] --> B["Select products"]
    B --> C["Create app or module template"]
    C --> D["Register module factories"]
    D --> E["Bundle manifests"]
    E --> F["Configure services and entitlements"]
    F --> G["Boot runtime"]
    G --> H["Activate modules"]
    H --> I["Run tests and guardrails"]
    I --> J["Switch production presentation"]

Loading

Runtime Change Workflow

flowchart TD
    Change["Runtime or API change"] --> Contract["Review public contracts"]
    Contract --> Tests["Add or update tests"]
    Tests --> Docs["Update README/wiki/API reference"]
    Docs --> Version["Confirm PR version behavior"]
    Version --> Guardrails["Run swift test and guardrails"]
    Guardrails --> Changelog["Handle changelog during release work"]

Loading

Documentation Ownership

Surface	Ownership
README	High-level repository entry point.
CHANGELOG	Release and change history.
GitHub Wiki	Comprehensive architecture and workflow documentation.
Source comments	Local API clarification only when code is not self-explanatory.
Tests	Executable behavior documentation.