MONOREPO USAGE GUIDE

Welcome to the d-a-s-h-o/universe monorepo! This repo contains multiple projects under a single repository, allowing for shared tooling, streamlined CI/CD, and easier cross-project updates.

🤔 Why a Monorepo?

By consolidating all projects into a single monorepo, we ensure:

• Easier asset sharing: Logos, icons, and shared libraries live in one place and can be updated across all projects effortlessly.
• Unified tooling: All projects benefit from the same linting, formatting, and CI/CD workflows.
• Simplified dependency management: Shared dependencies are updated in one go, preventing fragmentation.
• Cross-project development efficiency: If multiple projects depend on each other, changes can be made in one commit rather than across multiple repos.
• Consistent versioning: Semantic versioning across projects ensures better tracking of updates.

📝 Commit Message Format

To ensure clarity and consistency across all commits, use the following format:

[project] <emoji> type(scope): subject

body (optional)

footer (optional)

**Example Commits:**

[chat] 🚀 feat(auth): add JWT authentication

Implemented JWT authentication for user login, replacing session-based auth.

BREAKING CHANGE: Existing session-based logins will no longer work.

[droplets] 🐛 fix(api): resolve memory leak in data fetching

Updated request handling to properly close connections and prevent excessive memory usage.

Closes #42

[docs] 📖 docs(readme): update installation guide

Clarified setup instructions for new contributors.

**Commit Components Explained:**

• `[project]` → Specifies the affected project (e.g., chat, droplets, docs).
• `<emoji>` → Provides a quick visual cue (e.g., 🚀 for features, 🐛 for fixes, 📖 for documentation updates).
• `type(scope): subject` → Describes the nature of the change.
• Body (optional) → Adds more details if needed.
• Footer (optional) → Notes breaking changes, issue references, etc.

🏷️ Epoch-Based Semantic Versioning

All projects follow an epoch-based semantic versioning system:

(EPOCH * 100 + Major).Minor.Patch

• EPOCH: A major reset of the version history (e.g., significant architecture changes).
• Major: Backward-incompatible changes.
• Minor: Backward-compatible new features.
• Patch: Bug fixes and small updates.

**Example Versions:**

• 101.2.3 → Epoch 1, Major 1, Minor 2, Patch 3
• 200.0.1 → Epoch 2, Major 0, Minor 0, Patch 1

**Tagging a Release for `chat/`**

git tag chat-v101.2.3
git push origin chat-v101.2.3

GitHub Actions will build and push:

• ghcr.io/d-a-s-h-o/chat:101.2.3
• ghcr.io/d-a-s-h-o/chat:latest

🚀 Cloning the Monorepo

This repo is large, but you don’t need to pull everything. Use sparse checkout to clone only the projects you need.

# Clone without downloading all files
git clone --filter=blob:none --no-checkout git@github.com:d-a-s-h-o/universe.git
cd universe

# Initialize sparse checkout
git sparse-checkout init --cone

# Checkout only specific projects
git sparse-checkout set chat droplets docs

# Checkout the branch
git checkout main

🛠 Working on Multiple Projects Simultaneously

Use git worktrees to keep separate working directories for different projects without switching branches.

# Create a separate worktree for chat
mkdir ../chat-worktree
cd ../chat-worktree

git worktree add . ../universe main:chat

# Create a worktree for droplets
mkdir ../droplets-worktree
cd ../droplets-worktree

git worktree add . ../universe main:droplets

Now, you can work on chat/ and droplets/ in their own directories.

📜 Viewing Commit History Per Project

To see only the commit history for a specific project (e.g., chat/):

git log -- chat/

To see a short log with one-line commits:

git log --oneline -- chat/

To see a graph view:

git log --graph --decorate -- chat/

🔄 Committing Changes Per Project

When making commits, scope them to specific projects using the defined commit format.

# Stage only files inside chat/
git add chat/

git commit -m "[chat] 🚀 feat(auth): add JWT authentication"
git push origin main

🔀 Branching Strategy

To keep things simple, branches should be used sparingly. The preferred approach is:

• Main branch (`main`): The stable, deployable version of all projects.
• Feature branches (`feature/<project>-<name>`): Used for developing major changes before merging into main.
• Hotfix branches (`hotfix/<project>-<name>`): Used for urgent fixes that need to be merged quickly.

**Creating a Project-Specific Branch**

git checkout -b feature/chat-new-ui

**Committing and Pushing to a Feature Branch**

git add chat/
git commit -m "[chat] 🚀 feat(ui): redesign chat interface"
git push origin feature/chat-new-ui

**Merging Feature Branch Back into `main`**

git checkout main
git merge --squash feature/chat-new-ui
git commit -m "[chat] 🚀 Merge chat UI update"
git push origin main

🔄 CI/CD Per Project

Each project has its own GitHub Actions workflow to ensure that CI/CD only runs when necessary.

Example .github/workflows/chat.yml:

on:
  push:
    paths:
      - "chat/**"

This ensures only changes inside chat/ trigger the workflow.

🔎 Listing Project-Specific Tags

To see all tags related to chat/:

git tag --list "chat-*"

❌ Deleting a Tag (If Needed)

If you need to delete a project-specific tag:

git tag -d chat-v101.2.3
git push origin --delete chat-v101.2.3

🔍 Additional Considerations

Handling Dependencies Between Projects

If projects depend on each other, use:

• Symbolic links (`ln -s`) to reference shared assets.
• Git submodules if external dependencies need version tracking.
• Shared libraries in a central libs/ directory.

Rollback Strategy

If a breaking change is introduced, roll back using:

git revert <commit-hash>

Or reset to a previous tag:

git checkout <previous-tag>

Security & Access Control

• Use protected branches for main to require reviews before merging.
• Consider personal forks for external contributors.
• Store API keys & secrets in GitHub Actions Secrets, never in the repo.

Monorepo Tooling

If scaling up, consider tools like:

• Nx / Turborepo for caching & task execution.
• Lerna for managing package-based workflows.
• Bazel for dependency tracking & builds.

Performance Considerations

• Use sparse checkout to avoid downloading the whole repo.
• Regularly prune old branches:

git branch --merged | grep -v "main" | xargs git branch -d

• Prevent large binary files by adding them to .gitignore.

🏁 Conclusion

This monorepo is designed to make managing multiple projects efficient while keeping dependencies and tooling centralized. Use sparse checkout, worktrees, and scoped CI/CD to keep your workflow smooth!

---

For any questions, open an issue or ping @Dasho. 🚀