Code Git.pdf

Git workflow Owner Chloé Briquet Tags Branches Commit Creating a pull request Reviewing a pull request Comments Rebasing changes Steps recap Daily workflow Rebasing main into your-functionality Merged PRs Maintaining a clean repository is crucial. It can prevent bugs to be pushed in production and e...

Git workflow Owner Chloé Briquet Tags Branches Commit Creating a pull request Reviewing a pull request Comments Rebasing changes Steps recap Daily workflow Rebasing main into your-functionality Merged PRs Maintaining a clean repository is crucial. It can prevent bugs to be pushed in production and eases resolving them when they go past our vigilance: you can know what was committed when. A recap of the steps to follow can be found at the bottom. A word of wisdom before starting: if at any point of the Git process you have a doubt, do not hesitate to ask for help a team member that is more comfortable with Git than you are. It's not a shame, you'll surely learn something, and it may avoid some irreversible damages. Likewise, do not force-push anything to the remote repository (the origin). That being said, sometimes it can be very useful to force-push something (you'll see that in Rebasing changes), so if you have to do it, always do it super carefully, on a branch no one else is working on, only when you know what you're doing, and only to the specific branch your working on: if you're the only one to have this branch fetched on your computer and that you messes with it on the repo by doing a wrong force-push, no one will be able to restore it. Git workflow 1 To keep your local git repo clean, you can follow these instructions. Branches You should never commit on the to the production. main branch, because this is a branch dedicated You should instead commit to a branch specific to the functionality you're developping ( your-functionality will be used in the examples). When this functionality is finished, you create a pull request and assign it to someone for them to review it. Once it's reviewed, the branch can be merged on main. Commit You should commit regularly: not just once at the end of the day. Divide your work into small parts, and commit when one of these parts is done. The message of your commit should be written in English, start with a verb, and describe what you have coded. Be careful as to what you commit: don't skimp on the git status command. Only commit a code that works. You should have the guarantee that, when something goes wrong, you can always go back to what you have previously committed and that it'll work. Pull request is a functionality on Github that allows you to publicly ask your team members to merge your branch into the main one. Before your code is merged, it should be reviewed by another team member. Being the lead developer doesn't prevent your code from being reviewed and commented by less experienced devs, and being a trainee doesn't prevent you from reviewing and commenting the code of more experienced devs. We all have things to learn from each other! Creating a pull request Once you think your functionality is done and you have functionally tested it so you're sure it works, make sure all the commits of your branch are pushed to the origin. Then go to the Github project and create a new pull request (PR). Usually, you'll have a message on the "Code" page to indicate that your branch had recent Git workflow 2 pushes and ask you to "Compare & pull request". If not, go to the "Pull requests" page and click on "New pull request". Either way, verify carefully which branch you want to merge into which branch: "base branch" should be main and "compare branch" should be the branch of your functionality. Then, wait for a team member to review it. Make the changes needed after the review. There can be several rounds of review until your code is considered mergeable. When it is and you have the team member's approval, it's time to merge. Choose either: the "Squash and merge" option, which will gather all of your commits into one: it allows for better readability. Your commit message (usually the title of your pull request) should clearly describe your functionality, for example: "Create newsletter". The description of your commit is automatically generated and consists in a list of all the commit messages of your branch. Review them, fix eventual spelling errors, and remove messages like "Fix typo" or "Fix after code review": they are not important. or the "Rebase and merge" option, which will apply your commits one by one on top of the main branch: it allows you to keep track of all the commits you made. To have a clearer history, you can clean your history by using git rebase -i and removing/renaming your commits. Then, merge. Kind reminder: you're not a bad developer if you receive dozens of comments on your PR. Comments are constructive. Reviewing a pull request When you're assigned (or assign yourself) to the reviewing of a pull request: 1. Set yourself as “Reviewer”, so that two persons don’t review the same PR 2. Go on the "Files changed" tab of the pull request Comments Read the code carefully, line by line. Pay attention to what has been removed and what has been added. Whenever something is (or feels) odd, write a comment: click on the blue cross that appears when you hover over the line of code you Git workflow 3 want to comment, write your comment and click either on "Add single comment" or "Start a review" (this latter option sends only one e-mail with all of the comments rather that one e-mail per comment and thus should be preferred). Your comment can be about several things, amongst which (but not limited to): a spelling error, a name of variable/method/class that you think could be better chosen, a part of code you think could be simplified, a part of code you don't quite (or don't at all!) understand, a commented line that was left behind, an empty line too many, etc. A comment is never a stupid comment. Regardless of what you're commenting about, always be kind. Avoid comments like "This is wrong" or "You shouldn't have done it like that". Your comment has to be constructive: when you don't agree with a line of code, rather ask why your team member did how they did, and ask what they think of the way you would have done it. If you're comfortable with them, don't hesitate to use emojis. It always softens the message. Rebasing changes If you don't know what rebasing consists in, you can read this article. As a reminder, git pull makes, under the hood, git fetch and git merge commands, and git pull --rebase makes, under the hood, git fetch̀ and git rebase commands. The two main reasons why you would need a rebase is if you need code that have been pushed on the main branch, for example if you work on a functionality that, at some point, needs a functionality another team member has been working on; or if your code needs to be up-to-date before putting your PR to review. To rebase these changes, follow these steps: 1. Go in your project (in your computer), make sure you're on your functionality branch, that it's up-to-date with the origin (or at least that the origin doesn't have more commits than you have in local) and that you have committed or squashed all local modifications 2. git pull --rebase=merges origin main. The rebasing operation will start and, hopefully, you won't have any conflicts. More often than not, you will have some, and your project will be put in "rebase mode". If you panick, no worries: you can always abort the rebase and go back to how it was, before calling for help. Git workflow 4 3. If needed, start fixing conflicts: your IDE can be of great help there! In PHPStorm, for example, you can go to Git > Resolve conflicts, double-click on each file that needs fixing and choose, line by line, what you want to keep from the code that comes from main and what you want to keep from your own code (you can also do a mix of that by writing what you want on the middle column). When the conflicts are solved, you may have to commit or run : follow what Git indicates you. You may need to resolve several times the same conflicts because your commits are applied to the git rebase --continue commits from main one by one, and you have to fix the conflicts commit by commit. That's a not-so-funny moment to pass, but ensures you have a cleaner history 4. When all potential conflicts are resolved and the rebase is done (congrats!), you have to push these changes to the origin. Problem: as you can see, the commit history from your local project now diverges from the origin. This is when you have to ⚠️force-push ⚠️your changes. If you're absolutely sure, do it: git push --force origin your-functionality. To be even surer, you can use git , which ensures that no new commits have been added on your origin branch while you were rebasing in local. push --force-with-lease Kind reminder: never rebase your branch if it is public (if someone else is also working on it). Steps recap Daily workflow 1. At the root of your project, when starting a new functionality, make sure that you're on the main branch and that it's up-to-date with the origin main. 2. git checkout -b your-functionality will create a new branch from the main one. 3. Code what you have to code. Commit regularly. Push to the origin. 4. When you think it's finished and you have functionally tested it: create a pull request. Pull requests > New pull request. Base branch: main , compare branch: your-functionality. 5. Wait for someone to review your PR. Git workflow 5 6. Make the (eventual) needed changes. (Code, commit, push.) 7. Choose the "Squash and merge" or the "Rebase and merge" option. 8. In case you chose "Squash and merge": Check the commit message and the commit description. Remove useless lines like "Fix typo". 9. Merge! Rebasing main into your-functionality ⚠️Do not rebase a public branch ⚠️ 1. At the root of your project, make sure you're on that it's up-to-date with origin. 2. your-functionality branch and git pull --rebase=merges origin main 3. Follow the instructions: if there aren't any conflict, you're lucky. Otherwise, resolve them. 4. git rebase --continue everytime you resolved the conflicts for a given commit. 5. When the rebase is done and you're absolutely sure it went well: git push -- force-with-lease Merged PRs It happens that, for several reasons, a PR needs to be merged into main without having been reviewed first. It still needs to be reviewed. In this case, below workflow must be followed: 1. Merge PR 2. ⚠️Do not delete branch 3. Add tag “ 🙏 review” Developers need to check for PR to review in opened Pull requests but also in closed PRs. An “already-merged” PR should be reviewed the same way an opened PR is. If there are no comments to make (PR is all good), reviewer removes the “ review” tag. Git workflow 🙏 6 However, if comments are made (changes are requested), the dev having developed the PR should then: 1. Reopen PR 2. Check out to the already-merged-but-not-deleted branch related to the PR 3. Rebase main (see ) 4. Make requested changes 🙏 review” tag removed. When PR is all good, it should be merged and the “ Git workflow 7