Contributing Code to Aperture Viewer - ApertureViewer/Aperture-Viewer GitHub Wiki

This document provides the mandatory technical guidelines for any developer contributing code to the Aperture Viewer project. Adherence to these protocols is a prerequisite for any contribution to be considered for inclusion.

Aperture Viewer operates under a Studio Model, with an internally managed development roadmap focused on high-velocity architectural innovation. As such, we are not accepting unsolicited code contributions or pull requests at this time.

These guidelines are maintained as a strategic resource for future, formally invited collaborators and for ensuring internal consistency.

• Branching Strategy
• Core Coding Conventions
• Commit Message Protocol (Strictly Enforced)
• Local Testing Mandate
• Pull Request Protocol
• License

• ALL development occurs on branches created from dev.
• Before commencing work, ensure your local dev is perfectly synchronized with upstream/dev. A rebase is strongly preferred to maintain a clean, linear history.

  git checkout dev
  git fetch upstream
  git rebase upstream/dev

• Create a new, descriptively named branch for the specific, authorized task:
  • git checkout -b feature/name-of-mission-feature
  • git checkout -b fix/issue-number-or-name-of-fix
• Direct commits to dev or master are a protocol violation.

1. Aperture Commenting Style (Mandatory):

   • Multi-line Aperture blocks must use // <AP:TAG> and // </AP:TAG>. The project lead uses <AP:WW>.
   • Single-line Aperture changes use // <AP:TAG/>.
   • When replacing upstream code, the original code must be preserved by commenting it out within an <FS:TAG>...</FS:TAG> block.
   • Rationale: This is a non-negotiable requirement for mission-critical code tracking and future maintainability.

2. Indentation:

   • Use spaces, not tabs. Configure your editor to 4 spaces per indent level. This aligns with upstream conventions and is mandatory for code hygiene.

3. General Style:

   • Adhere to the existing style of the codebase for bracing, spacing, and naming. When in doubt, consistency is the primary directive.

We require a rigorous, three-part commit message format. Non-compliant messages will require a forced rewrite.

Format:

Type: Concise summary (max ~72 chars)

(Blank Line)

Body:
- A detailed, verbose description of WHAT was changed and WHY.
- Explain the strategic or tactical problem being solved.
- Reference relevant mission directives or issue numbers (e.g., "Fixes #123").

(Blank Line)

Testing:
- A detailed, step-by-step procedure that another engineer can follow to verify the fix or feature.
- Include the testing environment (OS, GPU).
- This section is MANDATORY and must be sufficient to guarantee QA.

Allowed Type Prefixes:

• Feature:, Fixes:, Enhance:, Refactor:, Perf:, Build:, Docs:, Style:, Chore:, Test:

All changes must be thoroughly tested locally before a commit is made. This includes:

• A clean recompile of the entire viewer.
• Execution of the exact test plan that will be documented in the commit message.
• Verification that no new regressions have been introduced.

Pull Requests will only be accepted from authorized collaborators.

• Title: Must be clear and follow the Type: convention.
• Description: Must clearly state the "what" and "why," and explicitly link any fixed Issues.
• Testing Section: The testing procedure from the commit(s) must be copied into the PR description for the QA officer.
• Checklist: Acknowledge that your submission adheres to all protocols herein.

By contributing to Aperture Viewer, you agree that your contributions will be licensed under the GNU Lesser General Public License, version 2.1 (LGPL v2.1).