H2 Contribute Redux · Part 4: more working on simplifying git concepts

pages/04.Contribute/01.procedure/docs.en.md

@@ -33,9 +33,11 @@ OK, let's check our tools:
 
 1. **Git**: If you are a **GNU/Linux** user it is highly probable that you already have it installed (you can check in your software package manager or through the terminal with the command `which git`). If you are using **Microsoft Windows** or **Mac OS**, you can download it from [here](https://git-scm.com/downloads).
 
-2. **A text editor**: Although there are many of them, we suggest you to use one with **Markdown** format support and **Git** integration. Both, **Kate Editor** and **Atom Text Editor**, meet this criteria, and they are also Free/Libre and Open Source multiplatform software.
+2. **A text editor**: Although there are many of them, we suggest you to use one with **Markdown** format support and **Git** integration. Both, **Kate Editor** and **Atom Text Editor**, meet this criteria, and they are also Free/Libre and Open Source multiplatform software. But, **for practical reasons, we will only see how to work in Atom** (in the future we will include other tools).
+
+  **Atom Text Editor**: [Download](https://atom.io/) · [Source code](https://github.com/atom/atom)
+
 
-  **Kate Editor**: [Download](https://kate-editor.org/) · [Source code](https://invent.kde.org/utilities/kate)  |  **Atom Text Editor**: [Download](https://atom.io/) · [Source code](https://github.com/atom/atom)
 
 3. **A Disroot Gitea account**: In order to be able to submit your work, you will need to register an account on our **Gitea** instance (**Disroot** credentials will not work) and request access to our repository.
 

pages/04.Contribute/01.procedure/docs.es.md

@@ -0,0 +1,44 @@
+---
+title: Procedimientos
+published: true
+visible: true
+updated:
+taxonomy:
+    category:
+        - docs
+    tags:
+        - contribuir
+        - procedimiento
+        - estilo
+page-toc:
+    active: true
+---
+
+# Procedimientos Howto: ¿Qué quiere decir?
+The possibility of writing a tutorial and making it accessible to everyone in their own languages is fundamental in order to encourage and promote not only the use of free/libre and open source software but also collective thoughts and actions. So coordinating the amount of information to be written and translated is an important task, therefore we developed a basic set of steps to follow to help us achieve this goal.
+
+The process is rather simple:
+1. We get a copy of the files we are going to work on;
+2. we work locally on the files,
+3. and once we have finished, we submit the work.
+
+Sounds pretty easy, doesn't it? Well, it really is. Of course, every step of the process has its own set of actions, which we will see later on, but that is it basically.
+
+# What tools do I need?
+We use three tools for our work: **Git**, **a text editor** and **Gitea**.
+
+We choose **Git** for several reasons, the main one being our documents structure and code language. Even though there are many (and very good ones) translation tools which look more "user friendly", none of them fit our use case or have **Markdown** text format support out-of-the-box. In the best scenario, it will requires us to make massive modifications on the files in order to strip them down into several "text sections" or "strings". Another important reason is that **git** allows us to keep track on the changes made on those files, making it easier to manage and collaborate on them. And one more reason is that **Gitea** (our **Git** hosting software) has a lot of useful features to organize and improve the work in one single place.
+
+OK, let's check our tools:
+
+1. **Git**: If you are a **GNU/Linux** user it is highly probable that you already have it installed (you can check in your software package manager or through the terminal with the command `which git`). If you are using **Microsoft Windows** or **Mac OS**, you can download it from [here](https://git-scm.com/downloads).
+
+2. **A text editor**: Although there are many of them, we suggest you to use one with **Markdown** format support and **Git** integration. Both, **Kate Editor** and **Atom Text Editor**, meet this criteria, and they are also Free/Libre and Open Source multiplatform software.
+
+  **Kate Editor**: [Download](https://kate-editor.org/) · [Source code](https://invent.kde.org/utilities/kate)  |  **Atom Text Editor**: [Download](https://atom.io/) · [Source code](https://github.com/atom/atom)
+
+3. **A Disroot Gitea account**: In order to be able to submit your work, you will need to register an account on our **Gitea** instance (**Disroot** credentials will not work) and request access to our repository.
+
+  [**Register a new account**](https://git.disroot.org/user/sign_up) on **Disroot's Gitea** instance.
+
+Once you have these tools, it is time to set them up to start working.

pages/04.Contribute/02.git/1.working/atom/docs.es.md

@@ -0,0 +1,126 @@
+---
+title: "Atom"
+published: true
+visible: true
+updated:
+        last_modified: "October 2021"
+        app: Git
+        app_version: 2.33.0
+taxonomy:
+    category:
+        - docs
+    tags:
+        - contribute
+        - git
+page-toc:
+    active: true
+---
+
+# Working with Atom
+Now we can start **Atom**.
+
+The interface of **Atom** is clean and easy to understand. The left sidebar is your project's navigation tree, the middle window is where you edit files and bottom bar indicates number of changed files, current branch, quick pull/push to git.
+
+![](en/atom_01.png)
+
+Go to the File tab, select `Open Folder` and choose the directory you've just cloned (the `Howto` folder).
+
+You can open and work on multiple files in tabs or as split screen side by side.
+Unsaved files with local modifications are marked with a blue dot (depending on the theme you use of course).
+To save the file changes use the *File* menu or the *Ctrl+s* keyboard shortcut.
+
+**Before** you start working on the files, you'll need to create your own **branch**.
+
+## Creating branches
+Branches are basically your own private workspaces.
+
+Each git project has it's own **master** branch. Master branch is the main, *production* copy of the project. This branch is automatically synced with the website, so any change made to that branch are instantly visible on the website. That is also why adding any changes to the **master** branch is restricted only to the owners of the project.
+
+In order to start working, create your own branch. This will basically make a clone of the **master** branch.
+
+On the bottom-right corner of **Atom**, click on **master** (or any other branch name) and choose **New Branch**. Choose a name for your branch, something easy for other to know what you're working on, what your branch is about. For example if your planning to work on a nextcloud howto, call it "nextcloud_howto" or something similar.
+
+Press **Enter** on your keybord when you're done.
+
+![](en/atom-branch1.gif)
+
+Now, you need to **publish** your new branch so that it is created on the server. **Atom** will ask your credential. Use the one created for our git instance.
+
+![](en/publish.png)
+
+Switching between branches can also be done from that menu. Current working branch is visible on the bottom bar. Click on it: other local branches will appear.
+
+![](en/atom-branch2.gif)
+
+Once the branch is created and published, and you have change the current work on this new branch, you can create new files, modify existing ones, etc.
+
+## Committing changes
+Now you're working on your computer creating new tutorials or translating existing ones. Apart from saving changes to your laptop, you can/should also **commit** your changes.
+
+Committing changes syncs the work you've done on your branch to the git server. So a commit is a set of files created or modified. If the branch doesn't exist on repository, it will be created and all your modifications and new files will be uploaded to the server. In that case you can work on your files on multiple machines, or other people can take over, help working on your branch.
+
+To commit your changes need to:
+ - Make sure all files are saved
+ - **Stage all** the files you've modified and want to commit to the server
+ - Write a **commit message** (a short and very specific summary of what has been changed)
+ - Hit **commit** button
+
+ ![](en/atom-commit.gif)
+
+ Once the files are committed, it's time to **push** (send) them to the server:
+ - Open Push/Pull popup window
+ - Press Push
+
+ ![](en/atom-push.gif)
+
+
+## Merge request
+Once you think your work is finished and ready to be published on the website, it's time to merge it to the **master branch**.
+
+![](en/note.png) <br>**NOTE!!!**
+
+While you are working on your branch, other users possibly commit and merge their own changes, esp. if you are working on existing files. If those changes from the other users have already been merged to the **master branch**, the version of the files you changed may no longer be the actual ones and therefore the changes from other users may not be included in your files. In that state, if you want to let your changes be merged to the **master branch**, this process may be very chaotic.
+
+![](en/git-merge_chaos.gif)
+
+Luckily git is able to compare versions and to insert your changes into the updated file versions. To trigger this, you need to update your branch **before** you **Create** a **Merge Request**. By doing this you will spare the admins and yourself a lot of needless work:
+
+ - First of all is to make sure all the changes are committed
+ - Open Terminal (Linux)
+ - Switch to **Master Branch**: ***git checkout master***
+ - Update **Master Branch**: ***git pull***
+ - Switch to working branch: ***git checkout <Branch_Name>***
+ - Update your working branch from **Master Branch**: ***git rebase master***
+ - Verify the changes and commit the changes to the Server
+
+Now you can start with the final steps of merging your files to the **Master Branch**:
+
+- First of all is to make sure all the changes are committed.
+- Login to [https://git.disroot.org](https://git.disroot.org)
+- If you pushed any changes to the server on your branch, in the top right you'll see a **"Create Merge Request"** button that will open the merge request form.
+- Add a title
+- Add a descripton
+- Make sure the **source branch** is the one you want to merge from (the one you've been working on)
+- Make sure the **target branch** is the one you want to merge to (usually Master branch
+- Checkin the box **Delete source branch when merge request is accepted.** is also a good thing to do if you're completely done working on your branch.
+
+![](en/git-merge_request.gif)
+
+Once you've created a merge request, it will be reviewed by **Disroot** admins and, if it's all right, they can approve your commit then. This means your changes will be merged with the master branch and therefore visible on the website.
+
+If there's any issue, admins could request you to correct something. Once all the corrections are made and the documentation meets the **Disroot** guidelines, your merge request will be pulled to the master.
+
+## Pulling changes from the server
+If you want to keep the local **master** branch and your local branch up to date, you'll need to pull changes from the server.
+
+Each time someones gets his merge request pulled in to the master, everyone should also pull the changes to their local branches. Then you can easily see what's new and what has changed recently. On the master branch we keep a file called **CHANGELOG** where we note all significant changes to Howtos.
+
+Pulling should be done on regular basis (specially before you start working on new branch).
+
+ - Open Push/Pull popup window
+ - Press **Pull**
+
+![](en/atom-pull.gif)
+
+## Template to use for how-to's
+You can copy the content [here](en/template.txt) and create your how-to file.

pages/04.Contribute/02.git/docs.en.md

@@ -18,11 +18,11 @@ page-toc:
 # Git?
 Yes, **Git**. It is a control version system, a software that allows you to track modifications to files, keeping a record of all the changes made, so if you need to revert to a specific version you can do it in a relatively easy way. It is also a powerful collaboration tool, since it allows many people working on the same files of a project.
 
-To learn the basics of Git and to work with it can be not only a very useful but also a fun experience.
+To learn the basics of Git and to work with it can be not only very useful but also a fun experience.
 
 
 # Scope of this tutorial
-Our use of Git doesn't require a high level of technical knowledge, anyone can learn the set of basic commands needed. And, to make it even easier, there are several text editors with Git integrated to reduce the interaction with the terminal to the minimum.<br>
+Our use of Git does not require a high level of technical knowledge, anyone can learn the set of basic commands needed. And, to make it even easier, there are several text editors with Git integrated to reduce the interaction with the terminal to the minimum.<br>
 So the aim of the following tutorial is to introduce you to the basics of Git, the main tool we use to manage the **Howto** project files. Therefore, we will not cover all the aspects of its usage, only some basic concepts and commands.
 
 If you get more interested about Git, there are lots of in-depth tutorials and documentation written about it that you can easily find on the internet.
@@ -31,30 +31,49 @@ If you get more interested about Git, there are lots of in-depth tutorials and d
 
 ![](en/git.png)
 
-When you read a **Disroot** tutorial, what you are seeing is the representation in your browser of a piece of code, in our case, a text file written in a formatting syntax called **Markdown**. The entire code of this site and its content is hosted in a **git repository**, a folder containing all the project files and the changes history of each and every one of those files (what has changed, who has changed it and why it has changed).
+When you read a **Disroot** tutorial, what you are seeing is the representation in your browser of a piece of code, in our case, a text file written in a formatting syntax called **Markdown**. The entire code of this site and its content is hosted in a **Git repository**, a folder containing all the project files and the changes history of each and every one of those files (what has changed, who has changed it and why it has changed).
 
-In this repository (or repo) there is a **main branch** (or "master branch"), the default project folder where is the "final" code, the one is online or in "production".
+In this repository (or repo) there is a **main branch** (or "master branch"), which is the default project line of development and from which different other branches can be created without compromising it.
 
 When a tutorial needs to be modified (e.g., some software has been updated, typos were found in a document, there is information to be added/removed, etc) or translated what we do is copy the remote repository into our machine, this way we can work locally on the files. This procedure is called **cloning** and once it is done, all Git operations are managed from our local repository.
 
+## Cloning the **Howto Disroot** repository
+As we mentioned before, the process of getting a copy of all the files within the project is called "**to clone**" a repository. And once we have the clone (the copy) of the repo, all modifications will be done on this copy in our local machine (most of the work is done offline).
+
+To clone the repository just open a terminal, navigate to the directory you would like to clone the repository to, and run `git clone <url>` command, where **url** is the address of the repository you want to clone. In our case it would be:
+
+`git clone https://git.disroot.org/Disroot/Howto`
+
+If you want to translate a page from the **Disroot Website** then type:
+
+`git clone https://git.disroot.org/Disroot/Website`
+
+The process will then begin and in a few minutes, depending on our internet connection, we will have the repository "copied" on our machine.
+
+![](en/cloning.png)
+
+Once the repository is cloned to your hard drive you will see a `Howto` (or a `Website`) directory that content all the files of the site.
+
+You can later move that directory to any place you want on your computer.
+
 Next step will be to create a new **branch**, a fork of the main branch on which we can make modifications without compromising the original code.
 
 ![](en/git_branches.png)
 
-But before we really get to work, let's setup your **Gitea** account so we can move forward without distractions.
+But before we really get to work, let's setup our identity so we can move forward without distractions.
 
-## Setting your Gitea account
-In order to be able to send your work from your machine to the remote repository, it is necessary to setup your **Gitea** username and email and request access to it.
+## Setting your identity
+In order to be able to send your work from your machine to the remote repository, it is necessary to setup your username and email, this information is used by Git to "sign" your commits (the "snapshots" of your modifications, we will see this later on).
 
-1. Open a terminal and start Git<br>
-`git init`<br>
+1. Open a terminal in (or browse to) a directory/folder where you want to clone the repository. In our example, we will be doing it in a directory called "Disroot" in the home folder.<br>
 
 2. Type and complete with your information the following commands:<br>
 `git config --global user.email` **user@email** `<- here goes your email address`<br>
-`git config --global user.name` **"User Name"** `<- and here your username`
+`git config --global user.name` **"Username"** `<- and here your username`
 
 You will not need to enter this information again.
 
+## Requesting access to the Disroot repository
 The faster and recommended way to request access is via our **Howto Chat room** at `howto@chat.disroot.org`. You can also send us an email to `howto@disroot.org`.
 
 Once admins grant you the access, you will be able to "*push*" your changes to the server.
@@ -62,22 +81,4 @@ Once admins grant you the access, you will be able to "*push*" your changes to t
 !! **NOTE**<br>
 !! You can start working without access granted as all the changes happen on your local computer.
 
-## Cloning the **Howto Disroot** repository
-Ok, now we need to get a copy of all files within the project onto our local hard drive. This process is called "**to clone**" a repository. And once we have the clone (the copy) of the repo, all modifications will be done on this copy in our local machine (most of the work is done offline).<br>
-When we have decided that the changes (new tutorial, translation) are finished we can sent/sync them back to the repository on the server, this action is called **push**.
-
-
-To clone the repository just open a terminal, navigate to the directory you would like to clone the repository to, and run `git clone <url>` command, where **url** is the address of the repository you want to clone. In our case it would be:
-
-`git clone https://git.disroot.org/disroot/Howto`
-
-If you want to translate a page from the **Disroot Website** then type:
-
-`git clone https://git.disroot.org/disroot/Website`
-
-Once the repository is copied to your hard drive you will see a `Howto` (or a `Website`) directory that content all the files of the site.
-
-You can later move that directory to any place you want on your computer.
-
-
 Ok. Now we finally can start to work.

pages/04.Contribute/02.git/docs.es.md

@@ -0,0 +1,83 @@
+---
+title: "Git"
+published: true
+visible: true
+indexed: true
+updated:
+taxonomy:
+    category:
+        - docs
+    tags:
+        - contribute
+        - git
+        - settings
+page-toc:
+    active: true
+---
+
+# Git?
+Yes, **Git**. It is a control version system, a software that allows you to track modifications to files, keeping a record of all the changes made, so if you need to revert to a specific version you can do it in a relatively easy way. It is also a powerful collaboration tool, since it allows many people working on the same files of a project.
+
+To learn the basics of Git and to work with it can be not only a very useful but also a fun experience.
+
+
+# Scope of this tutorial
+Our use of Git doesn't require a high level of technical knowledge, anyone can learn the set of basic commands needed. And, to make it even easier, there are several text editors with Git integrated to reduce the interaction with the terminal to the minimum.<br>
+So the aim of the following tutorial is to introduce you to the basics of Git, the main tool we use to manage the **Howto** project files. Therefore, we will not cover all the aspects of its usage, only some basic concepts and commands.
+
+If you get more interested about Git, there are lots of in-depth tutorials and documentation written about it that you can easily find on the internet.
+
+# What does Git do?: Basic concepts
+
+![](en/git.png)
+
+When you read a **Disroot** tutorial, what you are seeing is the representation in your browser of a piece of code, in our case, a text file written in a formatting syntax called **Markdown**. The entire code of this site and its content is hosted in a **git repository**, a folder containing all the project files and the changes history of each and every one of those files (what has changed, who has changed it and why it has changed).
+
+In this repository (or repo) there is a **main branch** (or "master branch"), the default project folder where is the "final" code, the one is online or in "production".
+
+When a tutorial needs to be modified (e.g., some software has been updated, typos were found in a document, there is information to be added/removed, etc) or translated what we do is copy the remote repository into our machine, this way we can work locally on the files. This procedure is called **cloning** and once it is done, all Git operations are managed from our local repository.
+
+Next step will be to create a new **branch**, a fork of the main branch on which we can make modifications without compromising the original code.
+
+![](en/git_branches.png)
+
+But before we really get to work, let's setup your **Gitea** account so we can move forward without distractions.
+
+## Setting your Gitea account
+In order to be able to send your work from your machine to the remote repository, it is necessary to setup your **Gitea** username and email and request access to it.
+
+1. Open a terminal and start Git<br>
+`git init`<br>
+
+2. Type and complete with your information the following commands:<br>
+`git config --global user.email` **user@email** `<- here goes your email address`<br>
+`git config --global user.name` **"User Name"** `<- and here your username`
+
+You will not need to enter this information again.
+
+The faster and recommended way to request access is via our **Howto Chat room** at `howto@chat.disroot.org`. You can also send us an email to `howto@disroot.org`.
+
+Once admins grant you the access, you will be able to "*push*" your changes to the server.
+
+!! **NOTE**<br>
+!! You can start working without access granted as all the changes happen on your local computer.
+
+## Cloning the **Howto Disroot** repository
+Ok, now we need to get a copy of all files within the project onto our local hard drive. This process is called "**to clone**" a repository. And once we have the clone (the copy) of the repo, all modifications will be done on this copy in our local machine (most of the work is done offline).<br>
+When we have decided that the changes (new tutorial, translation) are finished we can sent/sync them back to the repository on the server, this action is called **push**.
+
+
+To clone the repository just open a terminal, navigate to the directory you would like to clone the repository to, and run `git clone <url>` command, where **url** is the address of the repository you want to clone. In our case it would be:
+
+`git clone https://git.disroot.org/disroot/Howto`
+
+If you want to translate a page from the **Disroot Website** then type:
+
+`git clone https://git.disroot.org/disroot/Website`
+
+Once the repository is copied to your hard drive you will see a `Howto` (or a `Website`) directory that content all the files of the site.
+
+You can later move that directory to any place you want on your computer.
+
+
+Ok. Now we finally can start to work.