Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/MateoNavarroMN/Balsamoa-Backend/llms.txt

Use this file to discover all available pages before exploring further.

The Balsamoa team follows the Feature Branch Workflow: every piece of work — whether a new endpoint, a bug fix, or a documentation update — lives on its own short-lived branch and is integrated into main through a Pull Request. This keeps the codebase stable, makes code review straightforward, and ensures there is always a clean history of what changed and why.
The main branch is always production-ready. Never commit directly to main.

​
Branch naming

Use a consistent prefix so it is immediately obvious what kind of work a branch contains:
PrefixWhen to useExample
feature/Adding new functionalityfeature/endpoint-colores
fix/Correcting a bug or broken behaviourfix/error-subida-imagen
Branch names should be lowercase, use hyphens instead of spaces, and be descriptive enough that a teammate understands the purpose at a glance.

​
Full workflow

1

Sync main

Before starting any new task, make sure your local main branch is up to date with the remote. This prevents unnecessary merge conflicts later.
git checkout main
git pull origin main
2

Create a feature branch

Branch off from the freshly updated main. Use the naming convention described above.
git checkout -b feature/nombre-de-la-tarea
For example, if you are adding the colour-filter endpoint:
git checkout -b feature/filtro-por-color
3

Develop and commit

Work on your task and save your progress with frequent, focused commits. Each commit should represent one logical change — avoid combining unrelated edits in a single commit.
git add .
git commit -m "feat: descripción corta de lo que hiciste"
Follow the commit message format described below for consistency across the team.
4

Push the branch to GitHub

Publish your branch to the remote repository so your teammates can see it and so the Pull Request can be opened.
git push origin feature/nombre-de-la-tarea
If this is your first push for this branch, Git may ask you to set the upstream — running the command above handles that automatically.
5

Open a Pull Request

  1. Go to the repository on GitHub.
  2. GitHub will usually show a banner offering to open a Pull Request for your recently pushed branch — click “Compare & pull request”. If the banner is not visible, go to the Pull requests tab and click New pull request.
  3. Write a clear title and a brief description of what the PR does and why.
  4. Assign a reviewer from the team so someone is responsible for checking the code.
  5. Move your Kanban card to the “En Revisión” column.
6

Review, approve, and merge

The assigned reviewer reads through the changes, leaves comments if anything needs to be adjusted, and approves the PR once they are satisfied. After approval:
  1. Click Merge pull request on GitHub (use the default merge or squash merge — agree on this as a team).
  2. Move the Kanban card to the “Finalizado” column.
  3. Delete your local branch — it has served its purpose:
git checkout main
git pull origin main
git branch -d feature/nombre-de-la-tarea

​
Commit message format

Write short, clear, and descriptive commit messages. The project uses a simple type: description format: 
<type>: short description in lowercase
PrefixPurposeExample for this project
feat:A new feature or endpointfeat: agregar ruta GET /api/v1/tienda/colores
fix:A bug fixfix: corregir query de productos inactivos
Keep descriptions brief and in the imperative mood. A clear commit history makes it easy to understand what changed and why at any point in time.

​
Resolving merge conflicts

Merge conflicts happen when two branches modify the same lines in the same file. They are a normal part of collaborative development — not a sign that something went wrong. How to resolve them:
  1. Don’t panic. Git will list the conflicting files in the terminal output. No data has been lost.
  2. Open the conflicting file(s) in VS Code. The editor highlights the conflicting sections with clear markers: 
    <<<<<<< HEAD
// your version of the code
=======
// the incoming version from the other branch
>>>>>>> feature/otra-rama
  3. Read both versions and decide which one to keep (or combine them if both changes are needed). Delete the conflict markers (<<<<<<<, =======, >>>>>>>) once you have made your choice.
  4. Save the file, then stage and commit the resolution: 
    git add src/modulos/productos/modelo.productos.mjs
git commit -m "fix: resolver conflicto en modelo de productos"
If you are unsure which version is correct, discuss it with the teammate whose changes are involved before committing the resolution. It is always better to ask than to accidentally discard someone else’s work.
Keep your Kanban board up to date as you move through the workflow. The expected column progression for every task is:To Do → In Progress → En Revisión → FinalizadoMoving your card when you open a PR (→ En Revisión) and again when the branch is merged (→ Finalizado) gives the whole team instant visibility into what is being worked on, what is waiting for review, and what has shipped — without anyone needing to ask.

Build docs developers (and LLMs) love

Get started for freeTalk to us