├── README.md ├── assets └── backend │ ├── gif │ ├── fast-fix-dev.gif │ ├── hotfix.gif │ ├── intro.gif │ ├── main-flow.gif │ ├── remove-dev.gif │ ├── variation-release-commits.gif │ ├── variation-release-reuse.gif │ └── variation-two-feats-no-release-reuse.gif │ └── img │ ├── variation-release-commits.png │ ├── variation-release-reuse.png │ └── variation-two-feats-no-release-reuse.png └── gitflow └── backend └── README.md /README.md: -------------------------------------------------------------------------------- 1 | # Gitflow 2 | 3 | ![Alt text](assets/backend/gif/intro.gif) 4 | 5 | As there are many different projects at JS+, the teams use different gitflows that best suit each project! 6 | 7 | This repo contains some flows that are used by teams such as backend developers, frontend developers, etc.! 8 | 9 | ## Gitflow 10 | 11 | Here we have all the documented gitflows so far: 12 | 13 | - [Backend](gitflow/backend/README.md) 14 | -------------------------------------------------------------------------------- /assets/backend/gif/fast-fix-dev.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/juntossomosmais/gitflow/e09b8a705e09b4707dc9aee07d02479338bf3b3a/assets/backend/gif/fast-fix-dev.gif -------------------------------------------------------------------------------- /assets/backend/gif/hotfix.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/juntossomosmais/gitflow/e09b8a705e09b4707dc9aee07d02479338bf3b3a/assets/backend/gif/hotfix.gif -------------------------------------------------------------------------------- /assets/backend/gif/intro.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/juntossomosmais/gitflow/e09b8a705e09b4707dc9aee07d02479338bf3b3a/assets/backend/gif/intro.gif -------------------------------------------------------------------------------- /assets/backend/gif/main-flow.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/juntossomosmais/gitflow/e09b8a705e09b4707dc9aee07d02479338bf3b3a/assets/backend/gif/main-flow.gif -------------------------------------------------------------------------------- /assets/backend/gif/remove-dev.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/juntossomosmais/gitflow/e09b8a705e09b4707dc9aee07d02479338bf3b3a/assets/backend/gif/remove-dev.gif -------------------------------------------------------------------------------- /assets/backend/gif/variation-release-commits.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/juntossomosmais/gitflow/e09b8a705e09b4707dc9aee07d02479338bf3b3a/assets/backend/gif/variation-release-commits.gif -------------------------------------------------------------------------------- /assets/backend/gif/variation-release-reuse.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/juntossomosmais/gitflow/e09b8a705e09b4707dc9aee07d02479338bf3b3a/assets/backend/gif/variation-release-reuse.gif -------------------------------------------------------------------------------- /assets/backend/gif/variation-two-feats-no-release-reuse.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/juntossomosmais/gitflow/e09b8a705e09b4707dc9aee07d02479338bf3b3a/assets/backend/gif/variation-two-feats-no-release-reuse.gif -------------------------------------------------------------------------------- /assets/backend/img/variation-release-commits.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/juntossomosmais/gitflow/e09b8a705e09b4707dc9aee07d02479338bf3b3a/assets/backend/img/variation-release-commits.png -------------------------------------------------------------------------------- /assets/backend/img/variation-release-reuse.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/juntossomosmais/gitflow/e09b8a705e09b4707dc9aee07d02479338bf3b3a/assets/backend/img/variation-release-reuse.png -------------------------------------------------------------------------------- /assets/backend/img/variation-two-feats-no-release-reuse.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/juntossomosmais/gitflow/e09b8a705e09b4707dc9aee07d02479338bf3b3a/assets/backend/img/variation-two-feats-no-release-reuse.png -------------------------------------------------------------------------------- /gitflow/backend/README.md: -------------------------------------------------------------------------------- 1 | # Gitflow: Backend 2 | 3 | The main gitflow is very easy to follow, but includes some variations that might happen on our day-to-day work and are also explained here. 4 | 5 | **Content** 6 | 7 | 8 | 9 | - [Main gitflow](#main-gitflow) 10 | - [Summary](#main-gitflow-tldr) 11 | - [Variation: flow with commits on the release branch](#variation-flow-with-commits-on-the-release-branch) 12 | - [Variation: flow with two features on dev without releases](#variation-flow-with-two-features-on-dev-without-releases) 13 | - [If the two features cannot go together to production](#if-the-two-features-cannot-go-together-to-production-without-releases) 14 | - [If the two features can go together to production](#if-the-two-features-can-go-together-to-production-without-releases) 15 | - [Variation: flow with two features on dev with release reuse](#variation-flow-with-two-features-on-dev-with-release-reuse) 16 | - [If the two features cannot go together to production](#if-the-two-features-cannot-go-together-to-production) 17 | - [If the two features can go together to production](#if-the-two-features-can-go-together-to-production) 18 | - [Variation: hotfix](#variation-hotfix) 19 | - [Variation: broken dev](#variation-broken-dev) 20 | - [Fix it](#fix-it) 21 | - [Remove changes](#remove-changes) 22 | 23 | 24 | 25 | ## Main gitflow 26 | 27 | ![Main flow](../../assets/backend/gif/main-flow.gif) 28 | 29 | The main flow is easy to follow and the one we should strive to achieve. But, first things first, you should pair your local `develop` branch with what is on remote. 30 | 31 | ```bash 32 | git checkout develop 33 | git pull 34 | ``` 35 | 36 | Then, it's time to create your feature branch: 37 | 38 | ```bash 39 | git checkout -b feature/xpto # or git branch feature/xpto && git checkout feature/xpto 40 | ``` 41 | 42 | If your local development workspace doesn't have the `feature/xpto` branch, the command above will create it and switch your workspace to the newly created branch! 43 | 44 | Now, it's time to code! After you made your changes and think you have enough code to constitute a commit (a package with changes), create it with: 45 | 46 | ```bash 47 | git add changed-file # if you want to add all changes made to all files into one commit: git add . 48 | git commit -m "nice commit message" -m "More description" \ 49 | -m "How many paragraphs can I stack?" -m "I don't know" # or `git commit` to bring your git editor (usually `vim`) 50 | ``` 51 | 52 | Then, when you feel confortable, just push your changes to remote! 53 | 54 | ```bash 55 | git push -u origin feature/xpto 56 | ``` 57 | 58 | This will push any commit you did on your feature branch to remote and set the remote branch as a source reference to your local branch, so that any `git pull` and `git push` you do later, when working in this branch, is done referencing the remote one. 59 | 60 | Many `git add`, `git commit` and `git push` later, it's time to bring your new feature to the remote `develop` branch and update the development environment with your changes. But, before that, we want to evaluate what you did, checking if the changes address what the task asked, if there are enough tests, if the code can introduce any obscure bug, etc. And, for this, we run through a process called **Code Review**. It's an important step to prevent any undesirable change and to leverage the knowledge across the team. 61 | 62 | So, now, you need to create a merge request or a Pull Request (PR)! For that, use whatever tool you want! You could use the GitHub UI ([step guide](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request)) or the GitHub CLI tool ([manual](https://cli.github.com/manual/gh_pr)). After its creation, call for another DEV to review your changes. After some discussion and possible changes and only after you both agree that the feature can go on, merge your branch to `develop`! 63 | 64 | With everything smooth on our development environment, you can delete your feature branch and create a new release branch! 65 | 66 | ```bash 67 | git push -d origin feature/xpto # delete the feature branch from origin (remote) 68 | git checkout develop && git pull 69 | git checkout -b release/xpto 70 | git push -u origin release/xpto 71 | ``` 72 | 73 | Now, with the QA, or homolog, environment updated, call for a QA analyst to test your brand new feature! After her approval and with the product owner (PO) consent, create a PR targeting the main production branch (usually `master`) and call for another DEV approval. 74 | 75 | When it's approved, merge the PR and you're almost done! Take a time to monitor how your change affected the production environment and create a changelog to communicate everyone! 76 | 77 | And, now we're done! Congrats!!!! :tada: :tada: :tada: 78 | 79 | 80 | 81 | ### Summary 82 | 83 | 1. `git checkout develop && git pull` 84 | 2. `git checkout -b feature/xpto && git push -u origin feature/xpto` 85 | 3. Repeat `git add && git commit`, eventually `git push`, until the feature is done 86 | 4. Create a Pull Request (PR) targeting the `develop` branch and call for any DEV to review it 87 | 5. Do the requested changes, if necessary, until approval 88 | 6. Merge into `develop` and delete your feature branch 89 | 7. `git checkout develop && git pull && git checkout -b release/xpto && git push -u origin release/xpto` 90 | 8. QA Test 91 | 9. After QA and PO approval, create a PR targeting the `master`, or `main`, branch 92 | 10. After the PR approval, merge it and you're almost done! 93 | 11. Now, it's time to keep an eye if everything is fine with your feature in production and to create a changelog so everyone knows what you did! 94 | 95 | ## Variation: flow with commits on the release branch 96 | 97 | A very common situation that may arise once a new release branch is created is something that definitely has happened to every developer out there (unless, well, he wasn't a human at all): a bug. 98 | 99 | Even when the code seems to be working fine and all the tests are passing, things can still go wrong and hopefully you will have a QA analyst to help you identify the issue before the code actually reaches production. 100 | 101 | In these situations, the gitflow allows developers to make commits **directly to the release branch** in order to fix the release but comes at the cost of creating bugfix code outside the develop branch. This is bad as it drives the `develop` branch farther from the code that is actually going to production and this violates one of the golden rules of this gitflow: to keep `develop` and `master` as close as possible as **every new released feature will come from the development branch**. Hence, if commiting to the `release/*` branch is a must, then do it but **do not ever forget** to create two PRs when the `release/*` has been validated: 102 | 103 | - One PR to `master` (the actual code going to production) 104 | - One PR back to `develop` (yes, this is required to keep master, dev and future releases with the required bugfix code) 105 | 106 | So, here's the flow for this scenario: 107 | 108 | ![Variation Release Commits](../../assets/backend/gif/variation-release-commits.gif) 109 | 110 | And a final static image to illustrate the whole flow: 111 | 112 | ![Variation Release Commits Complete Flow](../../assets/backend/img/variation-release-commits.png) 113 | 114 | ## Variation: flow with two features on dev without releases 115 | 116 | This variation can be very common and depends a lot on how many developers are working with the same code base. This case usually happens when two or more developers finish writing their code on their respective feature branches, for example: `feature/feat-A` and `feature/feat-B`, and they both send their finished code to the `develop` branch. In this case, the `develop` branch will have **more than one new feature** at the same time. 117 | 118 | Notice that, in this case, NO release branches have been created. If a release branch already exists for one of the features, then skip to the next variation: [Variation: flow with two features on dev with release reuse](#variation-flow-with-two-features-on-dev-with-release-reuse). 119 | 120 | When this happens, **team communication becomes essential**: the **team** must decide if the two features can be shipped together to production or not. 121 | 122 | Let's discuss the two possible outcomes of the team's decision: 123 | 124 | ### If the two features cannot go together to production without releases 125 | 126 | If the team agrees that the two features cannot go together to production, and the two features are already on the `develop` branch, then `feature/feat-B` must be removed from the `develop` branch so that `feature/feat-A` can be used to create its `release/feat-A`. 127 | 128 | Once `feature/feat-A` has been shipped to production, then `feature/feat-B` can be used to create a new release branch: `release/feat-B`. 129 | 130 | `PS`: Bear in mind that this scenario may create **bottlenecks** as one feature will have to wait for the other one to be fully merged on `master` before being allowed to create the other release branch for the `feature/feat-B`. 131 | 132 | ### If the two features can go together to production without releases 133 | 134 | If the team has agreed to release the two features together, then the flow is very straightforward: as the two features are already on the `develop` branch, just create a new release branch that will contain the two features together that will be shipped to production: `release/feat-A-and-B` and proceed as usual with this release branch. 135 | 136 | ![Variation Two Features No Releases](../../assets/backend/gif/variation-two-feats-no-release-reuse.gif) 137 | 138 | And a final static image to illustrate the whole flow: 139 | 140 | ![Variation Two Features No Releases Complete Flow](../../assets/backend/img/variation-two-feats-no-release-reuse.png) 141 | 142 | ## Variation: flow with two features on dev with release reuse 143 | 144 | This variation can also be very common when the same code base is used by many developers. Here, one developer finishes writing his new feature, `feature/feat-A`, sends his code to `develop` and creates a release branch for his feature: `release/feat-A`. 145 | 146 | After this, another develop also finishes writing his new feature: `feature/feat-B` and sends it to `develop`. Now, this second developer **cannot** open another release right away as `release/feat-A` already exists and might be being used by the QA analysts. Two release branches opened at the same time can create a lot of confusion and must be avoided, specially because a new release branch will deploy different code to the qa environment! 147 | 148 | Once again, **team communication becomes essential**: the **team** must decide if the two features can be shipped together to production or not. 149 | 150 | ### If the two features cannot go together to production 151 | 152 | If the team agrees that the features cannot go together to production, then `feature/feat-B` that is on the `develop` branch will have to wait until the other feature, `feature/feat-A`, is fully shipped to production. After that happens, and `release/feat-A` no longer exists, then a new release branch, `release/feat-B`, can be created and submitted for QA analysts and PO approval. 153 | 154 | Remember that this scenario can also create **bottlenecks** as `feature/feat-B` will have to keep waiting on `develop` until `feature/feat-A` is fully released to production and `release/feat-A` no longer exists. 155 | 156 | ### If the two features can go together to production 157 | 158 | If the team has agreed to release the two features together, then the **release branch that already exists can be reused** to contain the two features (`feature/feat-A` and `feature/feat-B`) together. 159 | 160 | The most common way to do this by rebasing the `release/feat-A` branch onto the top of the `develop` branch that already contains the new feature `feat-B`: 161 | 162 | ```bash 163 | git checkout release/feat-A 164 | git pull --rebase origin develop # git pull with rebase instead of merge ~ git rebase develop 165 | ``` 166 | 167 | By rebasing the `release/feat-A` branch, this release branch will now contain the two features together (`feature/feat-A` and `feature/feat-B`). After this is done, proceed as usual with this release branch that contains the two features that will be shipped together to production. 168 | 169 | ![Variation Release Reuse](../../assets/backend/gif/variation-release-reuse.gif) 170 | 171 | And a final static image to illustrate the whole flow: 172 | 173 | ![Variation Release Reuse Complete Flow](../../assets/backend/img/variation-release-reuse.png) 174 | 175 | ## Variation: hotfix 176 | 177 | ![Hotfix flow](../../assets/backend/gif/hotfix.gif) 178 | 179 | Although this flow should usually be avoided, it might happen. So, when a wild serious bug appears in production and you need to fix it as soon as possible, it's time to create a hotfix! 180 | 181 | The first step is to create your hotfix branch from the main branch. Supposing it's `master`, do the following: 182 | 183 | ```bash 184 | git checkout master && git pull # remember to always be updated! 185 | git checkout -b hotfix/bug 186 | ``` 187 | 188 | After fixing the bug and adding some tests for it, it's time to create the PR targeting `master`. Then, after the changes integrate on production and you guarantee that it fixes the bug, you **must** create a PR for `develop` so that the fix is also integrated there. 189 | 190 | *__CAUTION: it may happen that at the time of the PR for `develop` (`develop` <- `hotfix`) there are divergences between the branches, as probably the branch `develop` will have been evolved. So the way to resolve conflicts is to merge manually from `develop` to `hotfix` before you open PR from `hotfix` to `develop`. However, if this manual merge occurs before the PR for the `master` to take effect, you will bring from `develop` unwanted changes at that moment to `master`!!! So only open a PR to `develop` after the merge to `master` is finished.__* 191 | 192 | Finally, don't forget to release the fix to the QA environment (creating a `release/*` branch from `develop` or following one of its variations). Although it can be done later, it's always important to have all environments stable and up to date! 193 | 194 | ## Variation: broken dev 195 | 196 | It's important to say that we should not break our development environment at all costs. It's shared between all devs and we need to ensure that it's stable enough so that everyone can work with and use it for their tasks. Saying that, we know that it can happen. We can break DEV, we can release into it a half-baked feature. And, it's totally fine, because: 197 | 198 | > To err is human 199 | 200 | Consider it a lesson to learn and if that happen, we have two alternatives: fix it or remove the changes from `develop`. 201 | 202 | ### Fix it 203 | 204 | ![Fix develop](../../assets/backend/gif/fast-fix-dev.gif) 205 | 206 | If possible, we should always try to fix `develop` before any other change, because the flow is simpler. As any other feature, we start a new branch from `develop` (or merge the `develop` changes into your broken feature branch) and follow the normal development flow! 207 | 208 | ### Remove changes 209 | 210 | ![Remove commits from develop](../../assets/backend/gif/remove-dev.gif) 211 | 212 | But, if we know that the fix will take some time, it's important to revert the introduced changes. For that we have two alternatives: 213 | 214 | - Reset the git codeline, as if the feature wasn't introduced to branch `develop` 215 | 216 | Suppose that you're at the top (`HEAD`) of your branch and the commit sitting there is a merge commit that came from your PR. If you want to remove it: 217 | 218 | ```bash 219 | git reset --soft HEAD^ # use `--hard` instead of `--soft` if you don't want the changes 220 | git push --force # be very careful! 221 | ``` 222 | 223 | This will remove the commits associated with the last merged PR and rewrite the git codeline. 224 | 225 | Notice here that we used `git push --force`. It's not something we should do with frequency because it affects everyone that is sharing the same repository and if someone just did a pull with your changes before the forced push, rewriting the timeline will just blew up her local repository. Thus, it's preferable to avoid it. That leads to our second approach: 226 | 227 | - Revert the commits, creating a commit that revert them 228 | 229 | Again, suppose that you're at the `HEAD` of your branch and the merge commit is the one sitting there. Then: 230 | 231 | ```bash 232 | git revert -m 1 HEAD # or the SHA commit you want to revert 233 | ``` 234 | 235 | The command above will create the commit you want, effectively reverting all the changes introduced with the merged PR. We can also do it using the GitHub UI ([step guide](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/reverting-a-pull-request)) and it's quite easy! 236 | 237 | The thing we should be aware is that if we want our changes back we need to revert the revert. So, again, do a revert: 238 | 239 | ```bash 240 | git revert HEAD # or the SHA commit 241 | ``` 242 | 243 | And continue your work! 244 | --------------------------------------------------------------------------------