Conventional Commits - #Git Tutorial for Absolute Beginners from Zero to Hero - Part 15

hey you lot here and davinci.com welcome to the last video in the git series today we're going to talk about conventional commits which is not only a way to format your commit messages but also an entire ecosystem of tools related to versioning your software and communicating those changes to the rest of the world let's get right to it [Music] before we begin i would like to mention that technically this video goes beyond git and so i would like to congratulate you for completing this course you are a local git hero now all right now our story for today begins in 2011 when tom preston werner a co-founder of github came up with a suggestion for naming the versions of your software we're not talking about the commit messages we're talking about the tags or what github calls releases i'm recording this video in the early 2021 and i'm happy to report that this suggestion became one of the most widespread conventions in our industry his suggestion revolved around the stability of the public api of your project if it's a library your api is self-explanatory if it's java it's some interfaces if it's c it's some header files if it's some web project if it's the backend of that web project then your public api is probably exposed over http or something similar if it is the front end of your web app project then the api is the actual elements on your website like buttons now not every change of your project effects or i should say breaks the public api but if it does then those changes will for sure affect the experience of your users for this reason this suggestion that eventually became a convention is called semantic versioning or short semver and you can read more about it on semver.org there are some depth to this convention but the tl dr is as follows you always have three numbers separated by dots a change that fixes a bug and does not break the api increments the last number a change that introduces a new feature but still does not break the api which means it introduces this new feature in a backwards compatible manner increases the middle number which causes the last number to be reset to zero and if your change finally does break the api then you increment the first number which in turn causes all the other numbers to be reset to zero again there are some details that i don't want to get into because this is not important to us this video is not about symmetric versioning for example you could have alpha versions or you could deviate from this convention when you're still at the you know 0.0 the zero versions and so on now i've talked about semantic versioning for a bit but i haven't actually explained why it is important the reason lies in the purpose of versioning in the first place a version is like a fingerprint of your software it denotes the fact that something changed semantic versioning goes a step further and allows you to estimate how big that change was this way you can make a judgment call whether to upgrade to a new version of a library or not nothing is guaranteed of course after all it's just a convention did the last number change easy decision we should definitely upgrade did the middle number change it's probably going to be fine do we really need the new features if we do let's try it out it's probably going to be fine did the first number change well sound you better have some decent test coverage let's have an example shall we if we run git version we're going to see that it's 2 30 0 and if we run update which is in this one let's go and do this i'm gonna cut it out from the video because i don't wanna waste your time so let's run git version again and we're gonna see that nothing updated and this is the reason why i actually don't like to use repositories git 230.1 was released a long time ago in fact i go over here we go over here we're going to click on release notes and we're going to see that there will not be that much right so it's zoomed in but it's like it's like five changes or something right because we know that it's just a bug fix release so um i'm pretty sure that it's even gonna mention the word bug or fix yeah fixes fixes fixes fixes blah blah blah okay so but if you go to 2030. zero which was a slightly major release then we're gonna scroll down scroll down scroll down we're gonna see a bunch of stuff was introduced okay semitic burning works let me mention a couple of more things related to december samver is a convention that heavily relies on developers discipline for instance in the scala ecosystem we starting to have a couple of tools that are trying to help you out they're trying to figure out whether you have broken source compatibility or binary compatibility but none of them are bulletproof another thing to note is that in practice for some reason a lot of open source projects rush out the stable version and then literally within hours or maybe sometimes days bug fixes are starting to roll in i really don't understand what the rush is can you just be water my friend and one last thing to know about summer is that even though this is probably one of the most widespread conventions out there there are actually alternatives for example in the haskell world there is a thing called haskell package version policy or pvp that you can check out over here at pvp.haskel.org now before we go any further i would like to note how important conventions and standards are the more we have the last time do we waste on bike shading but more importantly same as abstractions aka naming things breed more abstractions conventions breed more conventions and so today we're going to learn about a convention to structure your commit messages which is based on symmetric versioning which is also the reason why we just spent a lot of time talking about it afterwards we're going to talk about conventional change logs which is the ability to a generate a change log based on your conventional commit messages b automatically increase the version and maybe even commit it and c tag it on ci and maybe even d which goes beyond this video we could even start some ci processes based on that but again this goes beyond this video so we're not going to do it over here now one thing to note before we start with the conventional commit messages is that they don't change the native git commit messages guidelines they just add structure to it as a reminder the native guidelines are as follows the first one is use the imperative tone so use things like add and update instead of added and updated start with a lower case and don't end with a dot it's not sentences which is also why the imperative tone is used for instance add db migration or update docs or figsbug1337 another reminder these guidelines are only valued for the summary portion of the commit message in the body of the description you can do whatever you want i prefer to write out entire sentences or even paragraphs all right let's finally talk about conventional commits conventional commits came from the world of front and web development to be more specific they came from the contribution guidelines to the angularjs web framework let's actually go to conventionalcommits.org which i have over here and by the way notice it even has semantic versioning in the url it's very very simple so we're going to go through the website real quick all right this is a specification for adding human and machine readable meaning to commit messages and it's very very simple it's just a couple of lines even though the website you know you can scroll a little bit okay it says the conventional commit specification is a lightweight convention on top of commit messages it provides an easy set of rules for creating an explicit commit history which makes it easier to write automated tools on top of this convention dovetails with december by describing the future fixes and breaking changes made and commit messages the commit messages should be structured as follows you specify the type without the angular brackets it just is just the type now there is a set of types which is over here but you can also add your own the most important ones are feature and fix afterwards there is a column and in between you might add an optional scope for example if you're working on i don't know user analytics uh you can put in the braces you can put user analytics okay and then space and then you have the description which is the summary portion of your commit messages again git guidelines still apply something like you know add new feature or update this and that thing then you have an empty line and you have an optional body which is you know the body of the comment message this is the one where i use regular sentences or regular paragraphs and optionally you can have a footer uh in the footer you will either denote the breaking change right so you're gonna spell it out in the capital capital letters breaking change uh or you're simply going to add uh even more notes like for example um fix the bug number one three one three seven write some some zero ticket or some you know zero or club house or what have you now you can read through this in peace but the tldr we actually just went through uh please remember a couple of things uh there is there has to be a column over here it's very very important also the scope it has to be a noun uh which is not not super important but you know it's it's a part of the convention and also whenever you break a change right so we have whenever you break a change whenever whenever you have a breaking change uh when you're specifying in the food or breaking change uh you also can what you also can do is you can also put an exclamation mark uh i believe over here or over here in fact i forgot uh append after the type or scope right so it would be it would be over here right so the way it works is that if you add it over here you must have the breaking change below but if you specify on the break and change below uh then this thing becomes optional now if this is the first time that you're looking at this it sounds very complicated maybe but it's actually very very simple here a couple of examples for example you have a feature so you have feet which is a type then you have a column you have a space then you have your imperative message allow blah blah blah then space you know the the body is optional so you have breaking change column space and then you have you know you describe what you what you have broken or for example this thing over here the message was this draw attention to the break and change in fact i believe i might have explained this uh rolling before so if you have this thing then you don't need to specify uh breaking change like this so it was the other way around okay so in this one you have both you have like this thing and you also have this thing technically if your effector stuff uh you actually can't break this like as soon as you break stuff it's not a refactoring anymore commit message was nobody like this is the one that you're going to use most of the time i just added some dogs feature you specify a scope for for language you know at polish language um technically p should be capital um right so this is like the full-blown one right so you have a fix column space your summary uh your actual commit message i actually don't believe that there should be a space over here yeah so if there is a dot then this should have been capital if you want you know if you're creating a convention you know you might as well be thorough right reviewed by somebody references this right and this is the details of the specification but we actually don't really need to get into it like somehow they they managed to come up with 16 points right and there's an faq and stuff and you can go through it in your own um at your own pace and there are a bunch of tools we're going to go through a couple of tools in this video and that's pretty much it this is the conventional commits let me scroll back up cool so now this is a very very simple format but when you're starting out chances are that you're going to make mistakes uh luckily there is a bunch of tooling already built for you around this too to help you out and since it comes from the from the world of front-end web development uh all of these tools are written in javascript and so you need node.js because you need something to interpret this javascript we're going to see a couple of tools today a linter a commit message generator a conventional change load generator and also a conventional change load generator that also commits it and creates a tag for you let's start by installing node.js now a couple of videos ago we set up the environment for a scala project and uh we use grav vm and grout vm actually comes with a node and npm so if we do which node or if you do where node where is the functionality that comes from zsh i have a couple of awesome videos about the usage you might want to check it out so um the versions are a bit outdated so if we do this and if we do that uh so these days these table versions of of note is 14 and so we're gonna go and we're going to actually i haven't done which npm and where npm right so uh we're actually going to go and use one of my install scripts uh to to install node so we're gonna go over here we're gonna do node as always we're gonna copy the two lines uh from here and we're going to look into the script real quick um right so basically it basically installs node.js 14. uh all right so let's paste it over here let's press enter let's enter my password there we go okay as a reminder i have videos about this each uh you might want to check them out because this uh where thing it actually shows you uh all of the installed ones and not only the one that is the first on the path so for example if i go out now and go back in and i do i do which node and i do where node you're going to see that now i have a bunch of them but this is the one that i have in the class pass same thing for npm right so again where it comes from zsh all right so node version is this npm version is this uh version version like this all right great success all right so the first thing that we're going to install is a commit linter and we have quite a few things to tap out and so i prepared a thing for you where where i summed it all up it's going to be uh down in the description which is over here conventional installation instructions for ubuntu okay so these are pretty much all the things that we're going to do today okay so the first thing is to install node.js and now we're going to install commit in fact i'm going to start copy pasting things from here okay so we're going to install uh the commit lent which is a cli tool and we're also going to install this config conventional which is an adapter okay so conventional commits they have a couple of different adapters so there are technically a couple of different versions of conventional commits we're going to stick only to the defaults and i highly recommend that you also stick only to the defaults and so uh the majority of the tools that we're going to install um is going to look like this so we're going to install the tool you're going to install the adapter and they're going to be there's going to be some config where we're going to connect them to each other okay so let's go and install two of these tools we're going to install them globally one of the things that you should probably know that if you're running a node.js project then a lot of these tools are set up in such a way that they integrate really really well with node.js projects so you don't need to install them globally but since this is mostly a scalar channel we're going to install them globally over here we're also going to um to have the configuration files globally so that we can use it in any directory but even if you're not in a node.js project in practice you should probably have the configuration files inside of your repository so that all the developers use exactly the same configuration all right okay so let me copy these two lines let me go over here paste them enter my password a password come on there we go i'm actually not sure if it understood that i pasted two of them in any case i'm going to speed this up in the in the post production all right let me actually paste it again so that i'm i'm sure that i installed both of them yeah it didn't so this is the cli and this is the actual uh the actual adapter conventional change log there we go okay so now we have both the cli and the config conventional adapter okay so we're going to go back over here we're going to copy this line which just puts this string into this file and that's all it does all right so we're going to do this and in fact we're going to see it commit commit lend rc there we go so this is what we just put into this file all right so um now what we can do is we can pretend like we're having a commit message for example add export button and we can simply pipe it into commit lint like this all right there we go it says input and export button subject meaning bmt type may not be empty found two problems blah blah blah and then you realize oh i actually forgot to add you know something like this and now it says you know it's all good okay you can also do something like this i should probably use the regular quotes it doesn't like me like this there we go oh my god what happened here like this like this like that all right yeah so this one is fine uh you can also do something like i don't know user analytics so all of these are fine now commit linting is great this is your first line of defense but to be fair this is probably a rather a tool that is going to run with your continuous integration drops so locally you're probably not going to use it that often in fact we will use it locally we're going to put it into one of our git hooks uh git has a concept of hooks that we're going to learn about in just a couple of minutes but the other tool that you actually will use locally is going to be a commit generator it's going to make you a great commit citizen which is why it is called committism the same deal we need the tool and we need the adapter so we're going to grab the tools paste them in over here i wonder if it actually pieces both of them again like pasting multiple lines is sometimes um sometimes tricky and now the adapter in the meantime i'm actually going to go over here and i'm going to grab this line and again my uh script over here mentions that feel free to use the target local to your project right so you can create a dot uh cz or c uh in your in your directory okay instead of in the instead of in your home directory okay it's finished so let's do this let's actually look into it all it does it specifies the path to the uh to the adapter all right now let's actually create a repository so we have something to play around with we're gonna create a conventional uh playground i'm gonna call it uh repo and we're gonna do a g init and we're going to echo some stuff into a file and as a reminder there is gaa so we're going to add right and now we're going to run csat right so see that is the communism tool that we just installed i'm going to press enter and it's going to present it with this thing it says over here use arrow keys but you can also use jnk you cannot search and i'm pressing j and it just keeps keep scrolling as you can see you know there's chore reverse feature fixed doc style refactor okay so let's say that this is a feature so i'm gonna press enter okay what is the scope of this change uh again it's optional so you can just press enter uh but we can also do user analytics for example like this write a short imperative tense description of the change so for example we can do um add new feature feature like this and as you can see i use the sentence um communism can actually recognize a couple of things so it will lowercase the a for me and it will remove the dot however it's not bulletproof so if you have something like like an exclamation mark it's not going to notice this okay so just going to remove the dot and it's going to lower case the a okay longer description this is a longer description are there any breaking changes so if you want to press no you can just press enter or type in and i'm going to say yes and it's going to say describe the rake and change well i broke everything i broke everything like this does change affect any open issues well yes so i fixed number one to three there we go all right so now if we do something like this we see that we have you know feature user analytics column space and new features and if we do a good show it's gonna say all of these things so it created exactly what we have seen on the conventional changelog website now it is actually important to understand the architecture of this committee tool because actually the most power is in the adapter for instance you could change the adapter to use emojis instead of these topical words and then not only it's going to replace these topical words with the emojis but actually the entire prompt that we just went through is actually going to look very different now a big note about this if you're changing this then you should also change the adapter for the linter because it needs to understand the emojis okay also i highly recommend you not to use emojis because even though they look really really cool in my experience every time you're doing something special um you run into issues in the end and another thing that i should probably mention don't start using any of that stuff especially the emojis in your project before you talk to your team okay all right let's go over here and so we're going to grab the emoji one like this okay and i'm just going to paste it over here so while it installs i'm just going to copy this line as you can see it pays pretty much exactly the same thing into czrc it's just going to use a different adapter right so the pass is just going to change okay so it almost finished and there we go i'm going to paste this so let's go verify see that i see that rc there we go okay so what we need to do now is we need to pipe something else something else into the file add everything and run csat and now it's going to look slightly different first of all there is emojis right it says like you can use the arrow keys but you can also type to search right so for example in this case i'm going to say feature again so i'm going to type in f e there we go feature this is going to be the emoji right the rest is going to be similar but not the same specify a scope let's do user analytics okay write a short description uh add new feature and enter and i'm not going to do that over here for example it says a breaking change commit requires a body please enter a long description of the commit itself but i didn't tell it that we actually broke stuff so it actually assumes that if you didn't break stuff then you're just going to press enter and it's going to let you through okay list any issues closed no i don't have anything all right so if you now do this we're going to see that it used sparkles over here right so this is gitmoji and i should probably show it to you uh gitmod is over here so some dude picked up a couple of emojis that sort of fit into your you know fit into programming for example if you fix a bug it looks like a bug if you have you know sparkles introduces a new feature and so on and these are going to be rendered by git but they're not going to be rendered in your terminal and so what you can do instead is you can go and you can configure um see that emoji adapter all right so i'm just going to grab this as you can see it starts with the same thing right past c sees that emoji but then it adds the it adds the config okay so we're going to open um czrc okay and we're just going to delete this and paste that that's not what i wanted to paste delete delete and paste that there we go all right and so now what we're going to do is we're going to echo even more stuff into the file and then we're going to do csab okay same thing let's do feature um let's do user analytics uh add new feature and enter enter enter enter we don't really care oh i forgot to edit okay see that okay feature and uh user analytics and add new feature and enter enter enter enter and there we go okay so now this one is actually rendered properly but notice that technically the original conventional changelog format uh was very clear about a colon over here but this is a different adapter so technically it's a different format and for some reason it doesn't have a column i have a theory why it doesn't have a column because the original git modules they actually end with a column but still the column should be over here so yeah no idea again as a reminder if you want to actually use it then please also adapt the linter and um where do i have it here changes to the commit lint right so this is a link to um to this section over here this is a section of the commit effect let me enable this i hate it when it when it jumps around like this okay so essentially you introduce a new adapter and you put the configuration uh in there and it's going to uh lend your emojis as well all right so we're actually not gonna uh use emojis so i'm actually going to revert this to the conventional commit so i'm gonna you know to the regular one so we're just gonna do this there we go as a reminder i don't recommend that you use emojis uh for example first thing you need to do you need to change linter uh second thing you need to do is you need to decide whether you want to use git mode or or unicodes third thing that you're going to realize is that the unicode characters are not rendering all the terminals equally sometimes they are not rendered in uh in in tools um by the way if you have um the gitlands extension in visual studio code that i have showed you in the previous video um it uh shows you the git blame and it actually understands uh both the unicode characters and the uh the other ones so as you can see you can you can actually see it here it actually understands uh understands git mode as well i believe if we go go back um well in this view it doesn't it doesn't show it but you get the idea by the way one thing that i kind of jumped over is that if you know we just went to using the conventional commit we could have just changed it over here we could have left the conflict the config it's not a big problem if you have the config for an adapter that you're not using right let's go back you

Channel: DevInsideYou

Views: 2,833

Keywords: scala, software, development, programming, tutorial, dev, tutorials, code, learn, education, knowledge, diy, dev inside you

Id: JlfCRlFHmd8

Length: 25min 30sec (1530 seconds)

Published: Sat Apr 10 2021