Setting Up Your Codebase: The Blueprint

When you start a new coding project, it’s like building a house. You need a blueprint! This section talks about the different kinds of “houses” (repositories) you might build and how to set up your builder’s toolkit.

1. Repository Types: What Kind of Project Are We Building?

Think of a repository as a project folder for your code.

• Monorepo: Imagine a giant toolbox that holds all your different tools and projects. This is perfect when you have multiple related applications (like a website, a mobile app, and a backend service) that share common parts.
• Backend Repository: This is where the “brains” of your application live. It handles all the data, logic, and services that run behind the scenes.
• Frontend Repository: This is the “face” of your application—what users see and interact with, whether it’s a website or a mobile app.

2. Your Standard Development Environment (.vscode Folder)

To make sure everyone on the team is building with the same tools and following the same rules, every project folder needs a special .vscode folder. This ensures a consistent setup for anyone using VS Code.

Required Files:

• settings.json: This file is like a rulebook for your code editor. It makes sure everyone formats code the same way (e.g., uses spaces instead of tabs, automatically formats when you save).
• extensions.json: This lists recommended VS Code extensions, like tools for making your code look pretty (Prettier), checking for errors (ESLint), or understanding your code’s history (GitLens).
• launch.json (optional): If you need special settings to “debug” or troubleshoot your code, they go here.
• tasks.json (optional): For automating common actions like building your project or running tests.

Why Bother?

• Everyone gets the same coding experience, no matter their computer.
• New team members can jump in easily without struggling with setup.
• You avoid annoying “pull request” comments just about formatting issues.

Keeping Your Code Clean and Stable

This part is about making sure every change you make to the code is small, purposeful, and doesn’t break anything.

3. Atomic Commits & Automated Checks

An “atomic commit” means each change you save is tiny, focused on one thing, and leaves the project in a working state. Imagine it like making a single, perfect brick for your house—it shouldn’t be half-formed or cracked.

What Every Code Change Needs:

• It must build successfully (like confirming your brick is solid).
• It must pass linting (checking for style and potential errors).
• All unit tests must pass (small automated checks to ensure your code works as expected).

How We Enforce This:

• Locally: Tools like Husky and lint-staged check your code before you even save it, giving you immediate feedback.
• During Development: Automated “Continuous Integration/Continuous Deployment” (CI/CD) systems run these checks again before your changes can be added to the main project.

How We Work Together: Branching and Collaboration

Think of branching like making copies of your project to work on new features or fixes without messing up the main version.

4. Branching Strategy: Trunk-Based Development

This approach uses short-lived branches, meaning you make your changes and merge them back into the main project quickly. This keeps everything moving fast and your codebase stable.

Core Branches (The Main Highways):

• main: This branch always represents the code that’s currently live and working perfectly for users.
• stage: This is where all the new changes are gathered and tested together before being released to main. It’s like a rehearsal stage.

Working Branches (Your Personal Workspaces):

• feature/*: For building brand new features.
• bugfix/*: For fixing small issues.
• hotfix/*: For urgent fixes that need to go live immediately to solve critical problems.

Release Process: Changes move from stage to main during scheduled releases. We use a “Standard Merge” so that the full history of every tiny change is preserved.

5. Branch Protection Rules

To protect our crucial main and stage branches from accidental errors, we put up some safeguards:

• Pull Request Required: You can’t just push code directly; it needs to go through a review process.
• CI/CD Checks Required: All those automated tests and checks must pass.
• 1–2 Approving Reviewers: At least one (and preferably two) other team members must approve your changes.
• Commit Signing Recommended: This helps verify who made what change.
• Force Pushes Disabled: You can’t rewrite history on these branches.
• Branch Deletion Disabled: These important branches can’t be accidentally deleted.

6. Standard Development Workflow: A Step-by-Step Guide

Here’s how you typically work on a new feature or fix:

Step 1 — Start Work:

• You grab the latest version of the stage branch.
• Then, you create a new, dedicated branch for your task (e.g., feature/add-login-button).

Step 2 — Make Atomic Commits:

• As you code, you make small, focused changes and save them with clear messages (e.g., “feat: add user session handling”).
• You push these changes to your feature branch.

Step 3 — Create Pull Request (PR): Once your feature or fix is ready, you propose to merge your branch back into stage by creating a “Pull Request.” This PR needs:

• A clear title following “Conventional Commits” rules (like feat: add user session handling).
• A detailed explanation of what you did and why.
• Screenshots or GIFs if you changed anything visual.
• Links to any related issues (e.g., “Fixes #123”).
• Assigned reviewers to check your work.

Step 4 — Merge Rules:

• When merging a feature or bugfix branch, we typically “Squash & Merge,” which combines all your small commits into one clean commit for easier history.
• When promoting changes from stage to main for a release, we use a “Standard Merge” to keep the full commit history.

Step 5 — Cleanup: After your changes are merged, you delete your temporary feature branch to keep things tidy.

Code Style and Quality: The Look and Feel

This section is all about making sure our code looks consistent and adheres to high quality standards.

7. Code Formatting Standards: Tabs vs. Spaces

This is a universal rule:

• All code must use spaces, not tabs, for indentation.
• Standard indentation is 2 spaces.

Who Enforces This?

• Prettier: An automated code formatter.
• ESLint: A tool that finds and fixes style issues and potential errors.
• .vscode: Your editor’s settings.
• CI/CD: Automated checks during development.