Development Flow Conventions¶

This document provides a comprehensive guide to the development guidelines that we have been following and adopted within Forest. It reflects our current processes and seeks to promote standardization for greater consistency and efficiency in our flows.

Tools¶

• Git: For version control across all repos.
• Linear app: For ticket management.
• GitHub: humanforest organization for code repos management.
• Slack: For github integration notifications, on-demand tickets creation with Linear integration among.

Workflow¶

1. Ticket Management:

   • All work must be linked to a ticket in Linear.
   • Tickets are associated with the different teams (backend, frontend, etc) to ensure clear ownership and organization.
   • Tickets are also associated to an assignee who will work on it.
   • We are currently following weekly sprints to manage and prioritize tasks efficiently.
     • Sprint planning: Monday
     • Sprint start: every Tuesday.
   • Tickets effort estimations uses Fibonacci rule.

2. Branch Creation:

   • Linear uses the following format for branch names:

     {username}/{ticket-id}-{ticket-title}
     

   • Example: lucastorres/bac-799-add-dev-flow-conventions-to-documentation

     Tip: Use automatic branch names creation from Linear

     

3. Conventional Commits:

   • Follow the Conventional Commits format for commit messages:

     {type}({ticket-id}): {description}
     

   • Example: feat(BAC-799): add dev flow conventions md
   • Some of accepted commit types are:
   • feat, fix, chore, refactor, etc.

4. Pull Request Creation:

   • Use the following format for Pull Request titles:

     {Type(Ticket-ID)}: {ticket title}
     

   • Example: Feat(BAC-799): add dev flow conventions to documentation
   • Include a clear description of the changes in the PR body, some repos have already set PR templates, please follow them up.
   • Since the PR title has the Linear ticket-id, the current integration Github-linear will add a comment with the Linear ticker reference. But is a good option also add the reference in the PR description using the format Closes [Ticket-ID](linear-issue-url).
   • Request a code review before merging.

5. Review and Merge:

   • All branches must undergo a Code Review.
   • PRs must be linked to a Linear ticket.

   • Merge changes into the appropriate branch squashing commits:

     # Example: Squash commits locally
     git checkout main
     git merge --squash lucastorres/bac-799-add-dev-flow-conventions-to-documentation
     git commit -m "feat(BAC-799): add dev flow conventions to documentation"
     git push origin main
     

6. Slack integration:

   • To enhance visibility, we use a Slack integration with Github to notify the team of new Pull Requests in the following channel: #tech-pr-reviews.

Complete Example¶

Linear Ticket:¶

• ID: BAC-799
• Description: Create new page for development flow conventions as markdown in docs repo.

Workflow:¶

1. Branch Creation:

   git checkout -b lucastorres/bac-799-add-dev-flow-conventions-to-documentation
   

2. Commits:

   git add <files-to-add>
   git commit -m "feat(BAC-799): add dev flow conventions md"
   git push origin lucastorres/bac-799-add-dev-flow-conventions-to-documentation
   

3. Pull Request:

   • Title:

     feat(BAC-799): add dev flow conventions to documentation
     

   • Description:

     # Description
     
     This PR adds a page for development flow conventions to this documentation.
     
     ---
     
     Closes [BAC-799](https://linear.app/humanforest/issue/BAC-799/add-dev-flow-conventions-to-documentation)
     

4. Merge changes to main:

     git checkout main
     git merge --squash lucastorres/bac-799-add-dev-flow-conventions-to-documentation
     git commit -m "feat(BAC-799): add dev flow conventions to documentation"
     git push origin main
   

Best Practices¶

• Keep commits small and focused on a single change.
• Write clear and descriptive commit messages.
• Use appropriate labels in PRs to facilitate reviews.
• Ensure CI/CD passes before requesting a PR review, in cases such as infrastructure repo or fronted-related repos deployed to vercel, among others.