Ocean-Atlas Branching Strategy

• Ocean-Atlas Branching Strategy
  • Metadata
  • 1. Purpose
  • 2. Main Branch
  • 3. Working Branches
    • docs/
    • feature/
    • fix/
  • 4. Pull Request Flow
  • 5. Branch Lifetime
  • 6. Branch Protection
  • 7. Additional Branch Types

---

1. Purpose

This document defines the branching strategy for the Ocean-Atlas repository.

The strategy is intentionally lightweight and designed to support both knowledge contributions and future platform development without introducing unnecessary branching complexity.

---

2. Main Branch

main is the primary branch of Ocean-Atlas.

It represents the current integrated state of the project and should remain valid and usable.

Normal changes should not be committed directly to main.

Changes should be introduced through short-lived branches and pull requests.

---

3. Working Branches

Create a dedicated branch for each logical change.

Recommended prefixes are:

docs/<name>
feature/<name>
fix/<name>

docs/

Used for knowledge and documentation changes.

Examples:

docs/package-reference
docs/integration-guide
docs/ddd-concepts

feature/

Used for new platform or tooling capabilities.

Examples:

feature/atlas-validation
feature/search-index
feature/knowledge-api

fix/

Used for corrections to platform behavior, tooling, repository configuration, or other defects.

Examples:

fix/broken-validation
fix/ci-workflow

Minor documentation corrections may use either docs/ or fix/; docs/ is preferred when the change is purely knowledge-related.

---

4. Pull Request Flow

The standard workflow is:

main
  │
  └── create working branch
          │
          ├── make changes
          ├── validate
          └── create pull request
                    │
                    ├── review
                    ├── required checks
                    └── merge
                          │
                          ▼
                         main

Pull requests should target main.

After a pull request is merged, its working branch should normally be deleted.

---

5. Branch Lifetime

Working branches should be:

• short-lived;
• focused on one logical change;
• kept reasonably synchronized with main;
• deleted after successful merge.

Long-lived feature branches should be avoided where practical because they increase integration complexity.

---

6. Branch Protection

Where supported by the repository hosting platform, main should eventually require:

• pull requests before merging;
• successful required validation checks;
• required review for significant changes.

Protection rules may evolve as the project and contributor community grow.

---

7. Additional Branch Types

Additional branch conventions may be introduced when a real need emerges, such as release or maintenance branches.

They should not be introduced preemptively.

The branching model should remain as simple as the project’s development and release model allows.