 All right, welcome everyone. My name is Adam Shamanik and this is my Federa classroom about writing Federa documentation one-on-one. So what I'm going to talk about today is introduction, so I'll show you the new side that we got into production last week. Then I'll talk about Antora really quickly, which is the build engine. Also because not everyone is familiar with Git, I'll give you a brief introduction to Git and just show you all the commands you need to know to contribute to documentation and then I'll show you a complete workflow how to make a contribution to the docs from the beginning to the end and that will have some Q&A in the end. So introduction to the new site, this will be a live demo. But if I go to my browser and I'll just type docs.federaproject.org, this documentation has two main parts. So there is the user documentation and also the Federa project and community documentation. So let's have a look in the user documentation. Maybe I want to see something about 3.28. I just click on 3.28 and these are the three guides we already had. But there is a release notes. I have the installation guide and also the system administration guide. And this is basically the same content we had before in the old system. Just transformed here. I can go home. 27, that's the same for the Verohyd or all the releases. That's basically the same. I can also see the QuickDocs, which is a completely new way how we want to build documentation. And this is definitely not the final way it's gonna look. Now it's kind of messy and there are all these guides in the left menu and these are usually targeted for a specific thing. So for example, how to reset the root password if you forget it or I don't know how to view logs in Federa and even though this is not optimal, this will be one of the next steps we want to do in documentation and we want to change the view of this completely. That will be based on search and tags probably. But that's for the future. Some other sections here, Federa Project, Federa Council and also Engineering and Mindshare. And Engineering and Mindshare are basically the two basic to do the, sorry, I can't talk, the two biggest groups in Federa. So if I click on Engineering, there are some info. But one of the most important parts here is technical teams. Right now we have only one, which is Federa Modularity, but we can list many different teams here such as Federa Infrastructure, Federa Server Working Group, Federa Relange and basically anyone who wants to be here can be here and I'll even show you how to do that later. So I can go to the Federa Modularity site and see all the information here in the menus. The same is for Mindshare, Mindshare teams as well. We have one for the community operation, this is it. So that's how the new site looks like and now we should have a look how it works and how to make contributions to it. So we are using a new build engine called Antora. And even though I don't want to go into much technical details, I'll give you an overview of the structure, how the website is structured. So on this simplified image you can see that there is the website and it's built of many different components. There are called components in Antora and a component is basically a space with a menu on the left. So if I open the Federa Project, for example, this is a component. It has menu on the left, it has many pages here on the right and you can navigate in it. So that's how the website is structured very simplistically. But this is a little bit of a lie. This is simplification. Actually what's going on is this. So there are components which have one or more modules and these are still components are the places with the menu on the left, but we can separate them into smaller pieces called modules that can be stored in different source repos, which is useful if multiple groups want to own a different part of the same view with the menu on the left. One of the examples of this is, for example, the Federa user documentation. So if I go back to the site and I click on Federa 28, I'll see Federa release notes, installation guide and the system administration guide. These are three modules that are part of the one component. And by the way, we are calling many things modules these days. This is completely different than the concept of modular writing. This is just an entire view. So it can be confusing. I know. Let's just bear with it. And also, as I can see here, components can have multiple versions. So we have the documentation for 28, 27 or even more wide. And I can show you on the website right here. I can change it on the right. But if I go from 28 to 27, this changes the version. So this is basically the structure. We have the website that is built out of components. And these components are the places with the menu and can be divided into modules if you want to place them into the bread's source repos. And I said separate source repos. Yes, the website is built out of multiple git repos, each storing a specific part of the documentation. Each can be owned by a different group with different rules. And we just pull them into the builder and build a single large website. If you want to see all those lists of all those repos, you can go to this URL here. And I will also show you in a minute. This is the structure of the files and the template. And there are many different files. One is the component metadata. So it defines the name of the component and the versions that are accessible. And then we have those modules. If you only have one, which is basically most components will have only a single module. This is called root right here. And it contains all the things you need. So there are some images here. There is the menu definition and list of all the pages. So I can show you how it looks. They're an actual text editor. So I have gone to the repo and I can see the modules, pages, and these are many different pages. In the rhythm of the repo, there is also a way how to build a local preview. And I can maybe show you in the web browser because that will be much better. So if I go to the template URL, which is the URL on the slide. Here, the structure. And this is section called local preview, which describes how to do it. You basically only need a container runtime on your system and then everything just works. So I already have a container runtime. But if you want to install it, you can install, for example, Docker on Fedora using this command. Then start it up and it will work for you. So I'll just copy this command into the terminal where I have my template. So now it's building and it will show me the preview. And it's available here on the local host URL. I just put it in a browser right here. There we go. So this is the home page and I have the menu on the left. So how the menu is created and how the pages are structured. So if I go back to the editor, I can see the pages are all here, just at the same level. And there is also the nav adoc file, which very simply defines the menu as a list. So there is some xref, which I'll show you in a minute how it works. Or I can show you right now. So when I build the website and to recreate something called virtual catalog of all the pages and all the pages have a page ID, which is this and it's composed of a version, the component name, the module name, and then the page name with a local path if you want to have it organized in some way. And you can just take this and use it in the menu or anywhere in the documentation and put it here. And this is a little bit simplified because I am using the same component, the same module. So I can only list the page name. If you want to use images, these images are in assets and here. So on the index page, there is the image included. I can see it. So this is about the structure and now let's have a look how Git works. So we can actually do things with it. But if you don't know Git, I'll show you in three steps, very basic info about the Git structure, how to work with your own repo and then how to contribute to other repos, which is the useful part here. Git structure. So if you have a Git repo, it looks kind of like this. So there are four words that we need to learn with this. This is the repository or repo, commit, branch and head. So repo, repository is the place that holds the sources. And it's, for example, on Pagger. So we use Fedora Pagger. And if I go back here, this is a repo with the template. Then we have commits and commits are basically the unit of change to the source. So you have some source and if you change it in a way, we create a new commit which tracks the change and also have a name. I can also show you in the web UI. For example, recent commits are here. There are only two. There was an initial commit and then I switched it to Antora last week or 10 days ago. But usually there are many more commits. And also there are branches which are like versions of variants of the source. And in the example here, I have the installation guide, like three branches. And we have maybe three versions of the installation guide, one for F27, one for F28, and one for master, which is for the federal and Rohit. And that's where new features come. And then for example, Fedora 29 comes in, there will be a new branch F29. And then there is this head, which is the current view you see in your directories structure on your computer. And I will show you in a minute what it exactly means. So repo, commits, which are the units of changes and also branches if you want to track different versions. And if I want to work with my repo, I need to clone it. So there is a command to get clone. And we can, for example, clone the template here. So I do get clone and there are these URLs. There are two. Sometimes there's just one. The one with the SSH is usually if you're the owner, you can then make changes directly. Or the git one, which is only for viewing. And you can usually, you can't usually push changes into it. I have already cloned the repo here. I have the template, but I would otherwise do just get clone and the URL in there. So if I want to see this tree with the commits, I can use this command git log dash dash grab dash dash hold dash dash decorate, which is not very nice command, but it'll do the job. So I'll just paste it into the terminal. And I can see that there is a commit. It has some ID. There is the author of the commit. Then there is a message. There is the second one switch to Antora again, author and the commit ID. These are the branches. So for example, master is the branch here and also the head that is basically pointing to the master. So if I list the files, if I do LS, that's where the head points, right? And there are also origin master and origin head. And these are the remodels, repos on bagger. So I basically made a copy on my local system and I can then see the differences here. So if I want to change branches, I would do git checkout and branch name. For example, I want to make changes to the F27 branch. Then if I want to make changes, actually I'll use these four commands. So let me make some change so I can change the read me. For example, I'll use the beam. Read me. And I will just write this is test. I saved the file and now I can run git status to see the change. So git status. It'll tell me that there is one file modified and it's the read me. Read me file. The next one will be git add and the files. So I can type git add and the read me, which will add the file to a special place that will be. I will make the change from so it now if I type git status again. It's green because it's in this section changed changes to be committed. Well, before there were no changes to be committed. So this is called the staging area and all files I want to make, I want to commit. This will be, this needs to be added to the staging area. And then I can do git commit dash M and the message. So I'll just do git commit dash M and some message. This is just testing. Don't push. Example. And now I can see it with the log command. Again, if I find it in the history that there is a new commit. Oops. This is just testing. The head is pointing to it. It's called master on the local branch. And I can see that origin master, which is a master branch on the remote repo on the original repo is here. So if I now type git push, which I won't do this change will be applied to the repo on peggar. All right. So this is how you work with your repos. And now let's have a look how to work with other repos. So you don't usually have to commit permissions. And it's also to have your chain. It's also nice to have your change review. That's why we have a workflow of request. And this has four steps. So you make a fork, which is like a copy of the repo, but it's not your local copy. It's a copy in peggar. Then you can make changes, commit to your copy, make something called pull request. So conceptually it looks like this. You make a fork and it makes a completely identical fork and it will be on peggar. And I will show you how to do it. We will focus on the F 27 branch. So what you do, you create a new branch. And this branch will be referencing the same commit message as the F 27. Then you can make your changes and make a new commit. And you can see that the branch has a new commit here on your local copy. And then if you create a pull request, it will be merged into the original. And it will get your change. So this is very simple, the workflow of making changes. So you make a copy of the source. Make changes in your copy and then send the pull request that will be reviewed and include it in the documentation. So let's go through the whole thing, how to do it. And I will be showing it on the modularity documentation. So if I go to further docs, peggar.io slash further docs. I should probably put it in the chat. This is also in the slides in the end. So this is not pretty, but it just gets you here. You just click here and then you have a list of all the sources. In the future, there will be an edit button on each page of the documentation, but that needs to be done. It's not done yet. So right now we need to go here and see the list of all the repos here. And I want to make a change, for example, to modularity. So I just click on modularity and this is the repo. So first thing I need to do is to the fork. There will be your money button to create fork right now. I have a view fork because I've already did it because I've already done it because it takes like five minutes and it didn't want to waste your time. But you would click fork and it would do the same thing. You would just make a fork and now you will have to wait like five minutes for it to happen. And this is my copy of the further docs modularity repo. It's even written here. So what I want to do, I want to clone it. And I will clone it using this SSH URL so I can make changes. So I go to the terminal and I will do git clone the repo URL. And the name of the directory will be the same as the name of the repo, which is modularity. So I do cd modularity and I'm here. I can do the long command with the log. So this is the git log dash dash graph dash dash all dash dash decorate and I can see all the changes that happened here. This is the head that points to the branch master. And the last change will stand by me. And it's called fixed local preview. All right. What I want to do, if I go to the documentation, so this is the feedback docs. And I go to engineering technical teams for the modularity. And there is building modules locally. There needs to be no edit about some technical detail. I need to locate this file and make a change there. Again, in the future, there will be an edit button here, but it needs to be implemented if I take a while. So right now I'm doing this. So I'm in the repo here and I will open the repo in this editor. So the structure is modules. Then there is the root module, which is the main module pages. And it's under making modules and building modules locally. There we go. And I need to add a note here. And I have prepared the notes in a text file. And this is just a note for me that is why I don't need to waste your time and think about the notes. And I'll apply my change here. I think I'll put it here. So this is my change. Now I can preview the change in here. And if I do git status, it shows me that I have modified this file. I can also do git or git diff. Right now, yeah, git diff. And that's what I don't have in the slides. And it'll show me the change I have done to these files that are not added to the stage. So there is the note. And what I do is git add this. It adds it to the stage. It was red, git status. Now it's green under the changes to be committed. And I can do git commit add a note about local builds. I've made a commit. I can do the log command again. I can see there is my new commit and a note about local builds. And it's one commit ahead of the origin master. This is my local master. And now finally I can do push. So I just type git push. It's in there. And now if I view my fork. So I go back to the web UI of this. I refresh it. All right. It's the page. And there are recent commits. And it's here. Now I can do the change by clicking on it. And you can see there's been two lines added. One with the note and one with an empty line. All right. Back to the overview. So that was a change in my fork, in my copy on the server. And I want you to create a PR, a pull request. What happened here is that there is a new thing appeared, which says new PR. So I'll just click on this. But I could also go to the original repo. It's the same thing. And click on pull requests here. And I can select file new pull request. And it'll offer me my copy. So from assembly modularity in the master branch. So I'll just click here. I can confirm again. So this is my fork. This is the branch I used in my fork. This is the repo I want to put the change into a master. And I wanted to do, maybe add a title and a comment. So I don't know about local bills. This is just an info about the change. I'll just click create. And my pull request is here. And then someone else would come here, make a review for you. They can see the files that has been changed, the commits you would make, and they would do a merge. And because I'm the person responsible for this repo, I can do the merge myself. But this would be usually two people. So now I'm a different person from the docs team, for example, or from the team that maintains the sources. And I just click merge. And this way, in a while, it'll appear in the docs. In the main docs repo, and when we rebuild the documentation, you will also see it here. So that was the demo. And I think this is it right now. We saw how the Antara site is structured. So that's for a recap. Let me go to the slide there. We saw that there are components which are part of the menu. They have pages. Actually, it's a little bit complicated. Components have one or multiple modules, which are basically parts that can be put into other repos. We know that we can build it from multiple sources. There is a template repo you can try for yourself. You can just have a look how it's structured. This is the page ID that Antara makes out of every page. And you can use it for menu or also for local references in any other page in the whole documentation. Then we saw how Git works. Then we saw actual workflow. This is the end. Thanks for coming here. If you'd like to give me feedback, this is the URL. The Redox is here. And if you want to see the sources, it's this URL in the chat. If you have any questions, you can just ask here, or you can come to our IRC channel, which is Fedora-Docs on the free node. We also have a mailing list. You can, again, ask questions if you like. That's all. Thanks, everyone, for coming. I'll follow up with the slides and the video and maybe see some of you at Vlog or on the mailing list or on IRC channel. It would be great to have you there. Thank you.