How to Write Godot's Code Reference (contributor tutorial)

welcome in this video you're going to learn how to properly contribute to the Guru code reference more than that you are going to see the pull request workflow than most free and open source software projects use you'll learn to fork a repository to clone it to your local computer make changes open a pull request and follow the review process you'll see that once you learn to do that with one project you can pretty much follow the same steps with almost every project it's not true to say that everything uses it you will learn how to write a good reference how to do proper technical writing we'll share my experience with that starting with an overview of the process of the steps then you can find links in the description to jump to what you want to learn if you already know how to create pull requests you can skip ahead to just the technical writing part and the best practices if you want to contribute well some prerequisites you need at least a little bit of understanding of programming as in order to contribute to the class reference you will sometimes need to look at the source code of cadeaux which is quite accessible it's not as complicated as you might think even if you don't code in C++ you can still read the code and understand some of what it does but even if you can't do that you will at least need to test the functions in GT script to make sure that you understand what they are doing and so that can write precise Docs for other developers to use without further ado let's get started let us start with an overview of the workflow so you know what you are in for so first of all you can find the built in class reference in two places inside of Godot have the built-in search help that you can access with the f4 key you can find all the documentation and open it in the script editor and then you can also find it on the official manual that you can download for offline viewing at the bottom you have the glass reference and you can also browse it online of course but as a result even though you can find these pages on the docks that actually generated from gooders source code so what you want to do is to fork the repository and to edit the XML files that you will find inside of the dock folder classes subfolder so you have a number of XML files that you want to open in your text editor and this is where you edit the class reference so let me run you through the steps super quick before we cover each of them in greater details first you want to have to be good at repository and create a fork on your github account I've done that already and from there you will create a clone a local copy of your fork that can edit on your computer giving you a folder like that that contains the entire Google engine you'll need to set it up so that you have the copy your fork that can edit but that can also pull the changes from upstream from the original good--it engine so that you can update your local copy and your fork of the engine like so from there to coordinator will work without cluttering the official issues and the optional repository we have a document that can edit to let other Docs contributors know which classes someone is working on for example I've reserved all the animation node classes you don't want to create issues on the offshore repository because there are already lots of them and lots of people writing things and kind of forgetting about them so we don't want to clutter it more and working amongst ourselves on the documentation allows us to coordinate the work more efficiently so from there you'll want to head to the dock folder in your local copy of the gutted engine and find the XML file that correspond to the class that you want to edit you can then open it in your text editor so I have animation node add to open there and make your change but you'll want to create a branch to keep every single project that you do on the docks organized this is a very common thing when you develop in a team or on free and open-source projects I can do that from my text editor so I've done so for the animation knows that I'm working on I've already made some changes so you'll fill in between the tags the XML tags and all the documentation the reference that will end up in the go to documentation I highly suggest that you read complete documented classes to see how other people have written redux the written style and we'll talk more about how to write great changes and great reference from there you'll want to create a comet for your changes I'm still looking at the git commit from my text editor and you want to push it to your fork github is pretty smart from there it will offer you to easily create a pull request from the new branch that you created so when you do that it will directly open a pull request on the gute repository the official one with your commits name as the title and it will add all of your changes a single class here but you can then create a pull request so you'll want to request review from the documentation team and then follow guidelines some people might ask for changes if you made some typos or whatever can happen in we need to review each other's work to make the reference as good as can be so if you forgot a little something or made a small mistake or asked you to make a change which you can make inside of your file you can then update your commit false push to your branch it will automatically update your pull request so you just want to ask the documentation team to review your work and we'll also make sure to add the documentation label for you so that it's easy for other people contributing to Godot to know that your PR your poor request has to do with documentation from there someone will merge your work once it's ready and it will end up in Godot and you'll become a contributor this can seem a bit tedious but the reason while doing that is one hundreds literally nine hundred people working on the engine so we have to keep the work really organized and this workflow is really good for that it helps to keep the quality of the ducts and of the code really high up and to keep the project accessible so that more contributors can join in moving forward we're going to start by forking the go-to repository creating a copy of it on our github account that's separate and that we can manipulate however we want before we submit our changes to the Google engine on github being logged in you want to click on the phone button in the top right I've already forgotten as part of GE quest but you will have the option to choose on which accounts or organization you want to fork it going to head to the one I've created that should open a new page in your account or organization you'll have your name in the top left corner slash Godot form from the source project now we want to clone that repository so want to get a copy of it on our computer for that go to clone all download and you want to copy the link that you get here to clone from the command line by default you should see the HTTP link I'm using SSH another way to download it where I don't have to enter my password on the computer so I'm gonna head to that temporary folder and open my terminal then you want to get clone followed by the link to your copy of the good game engine so GD quest slash go to get and it's going to download all the files and the entire history of the project now I'm going to skip ahead once the download is done you can then find the entire coded engine on your computer I want to do a little more than what we have here so I'll enter the good directory like so on the command line see your cloned repository is not good to itself it's a phone call it it's a copy of the project that can manipulate now we do want a reference to the original project go to the engine slash Godot so that we can pull the latest changes that the other 900 contributors made to it and that we can base our work on the latest changes of other developers the same thing on go to the engine / go to on the source repository copy the link to the repository and we're going to add a remote what Gibbs calls a remote that is a reference to an online server where you have a copy of that git repository to do that you're going to type git remote if you press ENTER at this point you will see you have one called origin and origin is your fork it's the place somewhere on github server where you have your copy of the good engine to add a new remote you want to do git remote add and then you're going to name it we can name it upstream to suggest that this is the source of the project of this free and open source software and you then paste the link to it press ENTER to add the remote and now any type get remote you will see that you have two origin and upstream we freshly cloned the repository so we don't have new changes to pull but anytime you can then use upstream as a reference as a mount identifier for the source type also get for upstream and when you do so when you don't use just get Paul you have to specify the branch that you want to pull enjoy you will pull from the master branch the latest changes in the good game engine to do that any time be able to pull the new changes made to the docks made to the C++ files and then you want to push these new changes as well from time to time to your fork to do that you just do get push and that should do the trick once you've done that you want to use the docks tool and go to the duck status tool so in the garrote engine in the dark folder you'll find a tool sub folder and there you have duck status that py a program that you can use to check which parts of the Ducks are complete and which are not so open it in your command line and I'm going to expand the window so you want to call it with Python 3 and call the script dark status dot py and the tool if you just run it like that it's going to give you the help you will see the various flags now you need to pass it the folder that contains the classes and if you do so press ENTER you will get a large table that's going to show you the status of the Ducks if I go back to the top you will see the overall completion percentage for each class file and you will see if it's missing the brief description and description some methods constants members etc now you have quite a lot of classes in Godot so if you just want to work on those that are not complete you can use the same command with the dash B option and you will see that they're still 300 classes that are not 100% complete but then it already filters the list down a lot that you can focus on things that you can complete the dock status is based on that classes folder and the content of the XML files so that is why you want to pull the latest changes from upstream from time to time so that these files these XML files become up-to-date and so that the dog status is accurate time to get started writing the docs Here I am in the garage folder the good project source code and here is the same thing in Emacs my text editor going to go down the dock and classes folder to start editing the class and pick one of them I want to talk about how to get started writing the ducks so I've written a few for the animation node classes today and here's an example of one that's a bit tricky to do you have the animation node animation well the first thing you want to check is how these things work in the good editor right and in the case of the animation node classes they correspond to the nodes that you use inside an animation tree for 2d and 3d animation graphs if you check the label at the top of each of these cells on the add node menu you can notice that the names correspond to the end of the name of the class what's after animation node at two at three animation blend two etc so if I go to the add node menu you will find the same there so this tells you that these classes yeah correspond to these nodes in the animation tree so you want to play a bit with them and try to understand how they work so I'll help you write a description for them for example emission node animation I had to check in the editor what it does and it's just a reference to an animation that you can name using a label and then you can put it inside of the input slots of any other node that is going to blend animations together so this helped me write the base description of my animation another thing that helped me is because I can see that animation animation inherits from animation root node I could go to that class and read about it the animation let me find root node although it's incomplete here but it Han inherits from animation node this one and so I use what I found in animation node to get a sense for what all the derived classes were that's the first thing you want to do use the tool in Godot in the editor the second thing that you want to do I'm going to close that is to then use the nodes or the element you want to document from the code let us say I want to work on something we have used most of us like area 2d here so I'm going to open it you want to go to the editor say I want to document there's one called get overlapping areas it's already documented here I'm going to increase the font size let's say it was not documented well one thing you can do is open a project and here I have my snap detector that extends area 2d so you create a node that's going to derive from the class that you want to document and you use the method that you want to document okay and you check how it works you run a few tests through Gd script through your code this is a great exercise to train in Godot and at the same time it allows you to write some documentation so that's the second thing if with these two methods you can't documents precisely enough the methods or property that you are trying to write about you can skip it or if you feel like it you can go check the source code this is a little trickier but this is the next step if the other two methods I'm not enough to say I want to document this glass here animation notes state machine playback well I want to find it envy good at source code the best way to do that is to use some tags database which I have here in this editor I can do that automatically index a project source code and grab all of the classes the methods etc that it contains so here I am on the documentation but the class's name in C++ is the name that I have highlighted here and the editor right so I want to find it in the source code I'm going to highlight it and in my editor space max I can do space bj to search for tags fine tag in the project and it's going to give me what's highlighted what I've selected now so I'll press ENTER and this will take me to the where the class animation node state machine playback what a mouthful is created is declared and from there I can read about its properties and I can try to find some more information about it by default in space max at least it will take you to V dot H the header file and you want to go to the dot CPP file to find more information about how the methods of the class work because the header file is just going to define the structure of the class but the actual mechanics of the code are in the C++ file so here if I go back to the top I can find my animation nodes state machine playback so I'll go back to my C++ file and then you want to search your phone because these are pretty big even if I collapse all the blocks here you can see that this one is pretty massive so I'm going to do one of a few things in space max I can use space ji to jump to the that was machine and I'll search for playback and if I enter these patterns it's going to give me a list of methods of the class that that belong to state machine playback an emotional state machine playback and from there I can check whatever I wanted to document get travel path for example jump to it expand it and see that it just returns the path property so you can read the docs like that slowly and steady and from there use that to write the documentation so I'm gonna go back to notes state machine here state machine playback very good if you are trying to understand for example get traveled path it doesn't have a description returns that let's see if there's a path property in here there was a travel one returns the path state state state machine is travel traversing see for example I could reference the travel method this is really an example I'm going to reference method is it a method or a property that was a property called travel method so method travel in brackets this is going to create a link to that other method in the editors you can click it and jump instantly to the method in question so that's how to technically find the information you need to write the docs Here I am in another class you talked a bit about the writing style we have lots of people in the guru community and a lot of us are not native English speakers so want to make the documentation for one precise of course but also as accessible as possible without compromising on the precision and to do that we've written a few writing guidelines and that's multiple members of the community native speakers technical writers have contributed to try to write clear simple efficient English and ducks these aren't guidelines right these are not absolute rules that you have to end force in every sentence that the ideas here's a few things we can keep in mind to try to simplify our English one of them the first one is using the direct voice action verbs whenever you can so these are things for example the class the animation of blendspace one deep I start sentences with action verbs like outputs or it does something right you have methods you want to use action verb like the method add line point it adds a new point on the axis of the blend node 1z the one that you can find in the editor if a method is a getter and it just returns a value then we start with the word returns it returns some piece of information what you have with the return keyword in GE script so there's that use precise action verbs avoid using the transitive State I think that is verbs ending in ing because they tend to make the sentences a bit longer and heavier unnecessarily right same thing with adding adverbs and adjectives things like basically eventually those kinds of things they don't add any information to the sentence actually your words will have a bit more impact if your sentences stakin size it saves reading time if you add up all the adverbs that we don't need in the docs and it makes them a bit more formal as well some words are banned saying that things are simple easy those kinds of things because they really don't help programming is not easy in any case they don't add any valuable information to the documentation this is true of the code reference and of the manual as well and I will let you read the rest it's not very long in there are examples as well for each guideline that we added in there so go check it out you'll find a link in the description and use these to write your ducks I also highly highly recommend that you start by reading classes that have been worked out a lot and fixed a lot to get a sense for how the Ducks are written this is the case of area to D I can recommend something like a star I think it's it was pretty clean actually maybe I'm the one who wrote it I don't remember you can find kinematic body 2d those kinds of things so these classes have been read again and again and so people have had the opportunity to collectively fix the typos and those kinds of things in them it's about good examples of how to write code you can see that we have some elements in brackets in the documentation these brackets allow you to add BB code you can use let me increase the font size again so you can use BB codes like be to bold and I to add italic although we tend to avoid these we don't have strict rules for styling these but we don't use bold two too much however you have some specific cases if you put the name of a class the the name of it file here without the dot XML inside angular bracket this is going to create a direct link to that file in the editor and in the online doc you can see that you have the method keyword as well that can put before the name of a method this will create a link to the corresponding method inside of this file the method move and slide there you go you can use that as well when you use the method keywords in angular bracket can do the name of the class dot a method this is going to create a link to a method on another class instead of the method keyword you can also use a member keyword you can find this one down here member Oh too advanced it's going to create a link to a property or a member variable inside of that file and you can also do the same with the class name and the dot can type class name dot the member name and this will create a link to that classes file and to the member variable that corresponds to it let's talk about how to submit your changes to be good at project I just wrote this class the bone to d1 I'm going to start from the good--it folder where you cloned your repository let's open the terminal and I'm going to make it fullscreen here we want to first make sure that while not on the master branch if I run the command git diff I can see a comparison of the initial state of the project of the repository and the differences I brought the changes I brought in green you have B lines and added I have my changes I have not committed them I have not staged them even if I run git status you can see this have modified the document but I don't want to stall that modification on the master branch so I'm going to use git branch to create a new branch and I'm going to name it bone ducks bone to D there we go I've created a branch but I'm still on the master branch I'm still not going to store my changes in the right location if I do it now you want to switch the branch of the get tree you are on gets checkout to do that that's the command you want to give the name of the branch so dark bone 2d when I do that you can see now my command line tells us I'm on the duck bone to the branch from there I haven't done anything to my changes if I run git status you can see that I still have that file modified here so you want to commit that change to the git history this is a way of saying I'm sure that we want these changes I'm saving them right and before you can do that you have to stage them you have to tell git as part of this commit as part of this chunk of the project's history I want to add these specific changes here I only have one file I modified but when you work on a large project you may modify many files and you may want to commit that in separate chunks that are files that are related to one another or changes that are related to one another to stage the files we can commit it to the history you want to use the git add command you can use the star to add everything you've changed but in the case of our change I want to instead add the specific file the specific file path here so my command prompt if I just type start of the path that I have above here on the git status and press tab it's going to complete the path for me but otherwise you can type the entire path like that and you press Enter then if you are on the git status command again you're going to see now our change is in green it means if we run the git commit command this one will be stalled in the history and I would change so that is what we're going to do next git commit and you can then press Enter it will open a text editor where you can write your commit message in general it will open VI and lots of command so if you've never used that instead you may want to type - M and followed by a message - M is the option to follow by the commit message the first line is going to appear to everyone in the 'get history when you run the git log command so when you see below the author and the date in the 'get history log the line that you see here after the merge one that might be there as well where the the title that you see that is the first line of your message and this one is very important because in a large project like gato from time to time you need to go back in the history to see who did what change and why you know why they changed the code or the documentation a certain way the month might be explanations in the commit to understand why certain decisions were made in the past and this one I'm going to say add documentation for bone to D it's descriptive it's simple now if I have more to add I can jump one line and keep writing information for the readers but in this case we do not really just add documentation for and then you write the name of the class you change to me it works really well press ENTER to commit the change and so it's going to create a new comet now you can type git status again it can tell you you don't have anything left to commit but now our changes here on our local computer but it's not on our server so from there we want to write git push and then we'll do origin followed by the name of the branch so doc bone 2d okay that way we precisely push the change to the same same name branch on our Fork are we good at game engine this branch is going to be created by github for so press enter it will upload everything and from there we have to keep going with a navigator so I'm gonna go to github /gd quest slash the good engine just Godot so there github will tell you that you can compare your changes the branch that you uploaded and create a port request you click that button it will create a request to add your changes to the good engines master branch so the development version good at the engine itself you can see that the source of the change is your fork GG quest / module and that it's going to compare against bone 2d yeah so it's going to compare the new changes that you've added to it right this is the same as going to the source repository I'm going to the pull request section creating a new poll request and setting it up manually ok which is a bit more complicated so github makes it a lot easier there you will have your commit title as the title of the pull request and you will have a message here if you added some more lines to your commit message you can leave a comment for the people who are going to review your changes so from there you want to ask the documentation team to review your change so in the reviewers you click and you check for the documentation you ask them to review your changes the other things I can change because I'm a reviewer on we go to repository so I'm going to add the documentation label you won't be able to do that directly but someone moved from the docs team or someone from the Guru tree view team will do it for you and from there if everything is ready you want to click create for requests try to ensure that you have only one commit now you want to follow the review so from there other people are gonna come to these changes read them and give you some comments they might ask you to make some changes if that is the case here is how you do so I got some review on the animation note class and now I have to fix a few things so let's see how to do that for each of the comments that you are going to get you're going to see the file in which the comment is you're going to see the line that gets commented on the line that you change so you can jump to the line number in the file and in common that tells you what to do what you should change all you will have some discussion with the reviewer those kinds of things so I had a few changes to make over the eight files so I went back to my text editor and I changed the files you can see that to the yellow line on the side now I can show you the changes in my text editor for example for this file you can see how I modified some of the lines to add some information to fix some typos to add some links here and I've saved all the files so I've made all the changes one by one I use the line numbers you can see on the left to find what the person talked about but also sometimes if I have for example I had an issue in multiple files at once so there was that command that the range should be in code bbcode like that because as we use the brackets to create links and all those kinds of things in the docs the passer the program that converts this these XML files into Doc's might have trouble so I had four files that use the same pattern in this case I use a global search & replace to fix the file so in my text editor it's very good I can search in a folder like that and so I can start to type a regex pattern like so and from there I can take all these two a separate file press ctrl-z for here and here i am in a new file where i can modify each of the lines i can use a search and replace and commit these changes to the files directly that's how i modified them all at once so if you have the same change in several files i recommend that you use a process like this now it's time to upload the changes so i'm in the command line i'm going to show you how to do it with get from the command line although I normally use my text editor here I use this tool to commit everything so I'm using the Emacs text editor this tool in particular you can find an excellent intro to toriel by Gerald yeah you can see the link on-screen but to make it so all of you can follow along let's use the command line so to start we want to make sure that were back to the branch we were working on for that PR if not you want to use git checkout and go to the corresponding branch so dark animation nodes but already on it right git status to see the changes and get a hat to stage them so to prepare them for the commit I'm going to stage everything here because I want to update all these classes at once so now if I do get status you're going to see in green that they are all staged they're ready to be added to my previous commit because I don't want to create a new commit for that I want to add these changes back to my commit so that the go to commit history stays as clean as possible we'll just push one commit you want to get commit amend like so to modify your last comet so if I use git log to get a log the last of the the recent history of the project latest one here on the dock animation nodes is my commit add the documentation for animation note resources when you use git commit dash dash amend its going to edit the most recent one the one the head is on here by default so get commit amend we're going to press enter it will open the default text editor that you're using for get in my case it's Emacs yeah it will open that window with maggot at the bottom or majid where I can see all the new changes all the changes in this PR and so I can then press control C control C to commit the change okay and going back now to become in line you can see that the files have been updated properly so from there I want to push the changes to my fork to my repository not try to push it to the got it engine directly but to the origin removed I'll do git push and I'm going to do here I could do origin dark animation nodes like so and if you try to do that by default get will reject that will say no it's not possible see rejected the reason is we modified the history of the project if we were to push it straight who would overwrite the changes on the server the original commit and by default gets doesn't allow that that is why we have to use the dash F argument on the command I'm going to do git push origin duck animation nodes - F and just to explain origin is the name of the remote you're on pushing - and you're pushing to a specific branch note that in that case if you just use git push - f it would also works it's implicit that this is the server and the branch that you are pushing - but if you do that - F it's going this line to overwrite the changes once it's been done you can go back to your PR and automatically a git will show a new line saying that there have been some changes pushed there from there you can reload the page to see the little outdated tag on every line that you've modified right and from that the reviewers should be not fight but you can also add a new comment just fix and there we go so you do that every time a reviewer asks you to make some changes and once everything is done once you've fixed everything someone will merge it in the good at game engine for you that's it for this video so now you can get started contributing and don't forget that can join the IRC channel for the documentation team or the discount server where you can communicate with fellow contributors if you are struggling with something we always help one another among contributors and yeah we kind of have to because it can be a bit complicated to do our word sometimes now you can find links in the video description for the text version of this tutorial and to get started contributing see we'll find the link to the documentation issues on the good--it repository don't study related documentation I'm making this tutorial as part of the 2019 duct sprint event form good of 3.2 I invite you to join us with that all for future events to keep improving the manual the learning resources that are available with Godot and the built in code reference Thank You gang before watching be creative have fun let's see one another in the next one

Channel: GDQuest

Views: 3,572

Keywords: godot tutorial, godot class reference, godot become a contributor, godot contribute, godot 3.1, technical writing, write the docs, technical writer, contributing to free software, free software, open source, git workflow, pr workflow, creating a pull request

Id: 5jeHXxeX-JY

Length: 44min 21sec (2661 seconds)

Published: Mon Jul 15 2019