├── .github
    ├── ISSUE_TEMPLATE.md
    └── PULL_REQUEST_TEMPLATE.md
└── README.md


/.github/ISSUE_TEMPLATE.md:
--------------------------------------------------------------------------------
 1 | <!--- Provide a general summary of the issue in the Title above -->
 2 | 
 3 | ## Expected Behavior
 4 | <!--- If you're describing a bug, tell us what should happen -->
 5 | <!--- If you're suggesting a change/improvement, tell us how it should work -->
 6 | 
 7 | ## Current Behavior
 8 | <!--- If describing a bug, tell us what happens instead of the expected behavior -->
 9 | <!--- If suggesting a change/improvement, explain the difference from current behavior -->
10 | 
11 | ## Possible Solution
12 | <!--- Not obligatory, but suggest a fix/reason for the bug, -->
13 | <!--- or ideas how to implement the addition or change -->
14 | 
15 | ## Steps to Reproduce (for bugs)
16 | <!--- Provide a link to a live example, or an unambiguous set of steps to -->
17 | <!--- reproduce this bug. Include code to reproduce, if relevant -->
18 | 1.
19 | 2.
20 | 3.
21 | 4.
22 | 
23 | ## Context
24 | <!--- How has this issue affected you? What are you trying to accomplish? -->
25 | <!--- Providing context helps us come up with a solution that is most useful in the real world -->
26 | 
27 | ## Your Environment
28 | <!--- Include as many relevant details about the environment you experienced the bug in -->
29 | * Version used:
30 | * Environment name and version (e.g. Chrome 39, node.js 5.4):
31 | * Operating System and version (desktop or mobile):
32 | * Link to your project:
33 | 


--------------------------------------------------------------------------------
/.github/PULL_REQUEST_TEMPLATE.md:
--------------------------------------------------------------------------------
 1 | #### What is the purpose of this pull request?
 2 | <!--- Describe your changes in detail. -->
 3 | 
 4 | #### What problem is this solving?
 5 | <!--- What is the motivation and context for this change? -->
 6 | 
 7 | #### How should this be manually tested?
 8 | <!--- Remove if don't needed -->
 9 | 
10 | #### Screenshots or example usage
11 | <!--- Remove if don't needed -->
12 | 
13 | #### Types of changes
14 | - [ ] Bug fix (non-breaking change which fixes an issue)
15 | - [ ] New feature (non-breaking change which adds functionality)
16 | - [ ] Breaking change (fix or feature that would cause existing functionality to change)
17 | - [ ] Requires change to documentation, which has been updated accordingly.
18 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # VTEX Development Guidelines
  2 | 
  3 | ## Summary 
  4 | 
  5 | - [Overview](#overview)
  6 | - [Concepts](#concepts)
  7 |   - [Commits](#commits)
  8 |   - [Branches](#branches)
  9 |     - [Change Branches](#change-branches)
 10 | - [Workflow](#workflow)
 11 |   - [Other Scenarios](#other-scenarios)
 12 |   - [Issues and Pull Requests Templates](#issues-and-pull-requests-templates)
 13 | 
 14 | ## Overview
 15 | > **Disclaimer** This guide presumes that you know how to use git and the basic concepts of *commit, rebase* and *merge*. 
 16 | 
 17 | There is no right way to use Git. Therefore, we are defining our way to approach the change management of our codebase. This document is the guidance on using git workflow to simplify our development lifecycle.
 18 | 
 19 | ## Concepts
 20 | 
 21 | ### Commits
 22 | 
 23 | By simplicity, we have three types of commits:
 24 | - __*commits*__: commits made by the user 
 25 | - __*merge commits*__: commits through the commend `git merge <branch> --no-ff`
 26 | - __*release commits*__: commits using [releasy](https://www.npmjs.com/package/releasy) tool
 27 | 
 28 | [Releasy](https://www.npmjs.com/package/releasy) is a tool to simplify the versioning process of a project. It creates a commit with a new version in the `package.json` and creates a *tag* version to this commit.
 29 | 
 30 | Commit messages should be written in English following the model: 
 31 | ```
 32 | <Imperative verb> <object>
 33 | ```
 34 | 
 35 | Examples:
 36 | - Add PayPal Plus as a new payment method
 37 | - Fix profile not showing
 38 | - Update Service Router
 39 | - Remove unused dependency
 40 | 
 41 | 
 42 | What *not* to do: 
 43 | - Add dot at the end of text Ex: "Update Service Router."
 44 | - Start with lowercase
 45 | - Write in Portuguese
 46 | 
 47 | ### Branches
 48 | 
 49 | Every repository has a default branch called `main` (or `master` for old ones) with protected rules enforcing a peer review process. 
 50 | 
 51 | The `main` branch must reflect exactly what is in production, it should be treated as __*the single source of truth*__. It is from the `main` that every development branch is based. 
 52 | 
 53 | We have projects that also use a `beta` branch as permanent. This approach is adopt when the team wants to release several changes at once in production.
 54 | For those who adopt this approach, be aware that the `beta` branch can be constant override by the team. So, don't keep anything saved only in `beta`.
 55 | 
 56 | **Important note:** Only *merge commits* should be made on `main` and `beta` branches.
 57 | 
 58 | #### Change branches
 59 | 
 60 | You must create a branch based on the `main` to start a feature, improvement, or fix. We called this of *change branch*. It must have the following structure name: `<type>/<description>`
 61 | The `types` are:
 62 | - **feature:** Build a new feature or improvement
 63 |   - _feature/add-postal-code_
 64 | - **fix:** Fix a bug
 65 |   - _fix/bad-gateway-error_
 66 | - **update:** Update project dependencies, docs, runbooks, and so on
 67 |   - _update/otel-library_
 68 | - **chore:**  Refact to reduce complexity, remove unused code
 69 |   - _chore/remove-toil_
 70 |  
 71 | A description must be short in kebab-case. It should give a basic understanding of what is being developed on the branch. E.g., `git checkout -b feature/paypal-plus`.
 72 | 
 73 | **Important note:** Only commits and code reviews should be done in a change branch. Avoid **releasing** to production directly from this branch.
 74 | 
 75 | ## Workflow
 76 | 
 77 | ### Scenario: I want to develop a feature improvement 
 78 | 
 79 | **Step 1.** Create a *change branch* based on `main`.
 80 | ```sh
 81 | git checkout main
 82 | git checkout -b feature/nice-new-thing
 83 | ```
 84 | 
 85 | **Step 2.** Develop the improvement in this *branch* making commits. 
 86 | ```sh
 87 | git commit -m "Add nice new thing"
 88 | ```
 89 | 
 90 | **Step 3.** Do it a *merge commit* of this *change branch* in `beta` with a flag `--no-ff`.
 91 | ```sh
 92 | git checkout beta
 93 | git merge feature/nice-new-thing --no-ff
 94 | ```
 95 | 
 96 | **Step 4.** (optional - for those who use beta) Do it a *release commit* on `beta` using releasy.
 97 | If it is the only *change branch* in `beta`, use: `releasy`.
 98 | If it isn't, use `releasy pre`.
 99 | 
100 | **Important:** Certify that a published version has `-beta` suffix.
101 | 
102 | **Step 5.** After publishing the version, wait for the build on Pachamama to end and change the version published in Delorean.
103 | 
104 | **Step 6.** Test your improvement on the *beta* environment (vtexcommercebeta). If you find bugs,  go to your *change branch* back to step 2. Otherwise, continue to step 7. 
105 | 
106 | **Step 7.** Open a Pull Request and ask for a review. PRs are our friends. They ensure that we raise the bar of our code quality, find bugs and share knowledge with our peers. After your PR is approved, go to Step 8. 
107 | 
108 | **Step 8.** Do it a *release commit* in the *change branch* using the releasy.
109 | - Add a *minor* version in case of a "feature" or "update": `releasy minor --stable`
110 | - Add a *patch* version in case of a "fix": `releasy patch --stable`
111 | 
112 | **Important:** Verify that the version doesn't contain the `-beta` suffix. If it has, you forgot to use the *flag* `--stable` in releasy.
113 | 
114 | **Step 9.** Publish the *change branch* in production: 
115 | Put your commits in `main`, clicking on **Merge Pull Request**. 
116 | 
117 | **Step 10.** After publishing the new version, wait for the build ends on Pachamama and change the version in Delorean.
118 | 
119 | **Step 11.** Verify that the changes are in the *stable* environment (vtexcommercestable) and monitor the metrics to certify that your deployment didn't degrade the platform or your service. If you see something wrong, make the rollback in Delorean **immediately**! You can do the troubleshooting later in *beta*.
120 | 
121 | **Step 12.** Celebrate! 🥳 You published something in production for millions of people. 
122 | 
123 | ### Other Scenarios
124 | 
125 | **Someone update the `main` branch, and I'm developing something on my *change branch***
126 | Make *rebase* of your *change branch*.
127 | 
128 | ```sh
129 | git checkout main
130 | git pull
131 | git checkout feature/nice-new-thing
132 | git rebase main
133 | git push origin feature/nice-new-thing -f
134 | ```
135 | 
136 | **Important note:** Always maintain your *change branches* rebased on `main`.
137 | 
138 | ### Issues and Pull Requests Templates
139 | 
140 | A good practice adopted is to use templates for creating Issues and Pull Requests on Github that help you to describe what you are aiming to do with a change proposal. 
141 | To do that, you can copy the `.github` on this repository to your project repository. This folder has [PULL_REQUEST_TEMPLATE](https://github.com/vtex/dev-guidelines/blob/main/.github/PULL_REQUEST_TEMPLATE.md) and [ISSUE_TEMPLATE](https://github.com/vtex/dev-guidelines/blob/main/.github/ISSUE_TEMPLATE.md) files. Feel free to change these files, and also, **please give us feedback to improve these templates**.
142 | 
143 | Praise for the **order management** and **help-center** projects from which we get these templates. 
144 | 


--------------------------------------------------------------------------------