TechDocs/Git/Workflow

Common information

The workflow in Git is quite different from what you may be used to. This is because Git is decentralised. Every repository in Git is equal, but some repositories are more equal than others.

Before you start, make sure you have everything set up as described in TechDocs/Git/FirstSteps. Also make sure you understand basic Git commands as described in TechDocs/Git/FirstCommit

The Three Repositories

As a beginner, you only really need to know about three repositories that are relevant to you, and that you will interact with. For this guide, we will assume that we are working on fsfe-website. The three repositories are:

These three terms will consistently be used in this guide.

A note on branches

In Git, you will often be using branches. When you first visit a project's web page or first clone a project, you will see the master branch of that repository. This is the main branch in any repository.

Consider a branch like an independent alternate timeline of commits, where the master branch is the main timeline. So if you create a new branch from master, you are entering an alternate timeline that, from that point onward, is not affected by changes in master. You can merge that timeline back into master, though this is often done by the maintainer of the repository.

Similarly, when a new commit is added to the master branch of the main remote repository, that commit does not immediately appear on the master branch of your remote repository. You have to manually update this. This makes sense, because your repository is independently your own, and nobody else's.

You usually do not edit the master branch directly. Ideally, the master branch is identical between the main remote repository, your remote repository and your local repository, so that all repositories agree on the official series of commits. If you edit your own master branch, you are basically disagreeing with the main remote repository and creating your own "official" timeline. Which would be fine, if you were writing an alternate history novel, but you probably want to stick to the official master branch.

Guide

This guide is way to create a new pull request, i.e. a proposal for an addition or change of yours to the upstream repository, mostly via the terminal. This solution is preferred over using graphical application. This is because it is easier to ask someone to type a certain command, than it is to ask them to push some buttons. However, we also explain the process with a graphical Git frontend below.

Set up your repository

Assuming you have set up your remote repository by clicking the "Fork" button on the main project page, you can now set up your local repository.

Also, by cloning, you have implicitly configured a "remote" for your local repository. This remote is called origin, and is equal to "git@git.fsfe.org:YOURNAME/fsfe-website.git". You might want to add an extra remote, however, pointing to the main remote repository. Let's do this now, and call it upstream.

Syncing all repositories

Before you start, you may want to synchronise all repositories so that you are working on the latest version of the main remote repository (upstream).

Start on a new feature

Let's begin changing something, e.g. adding a new translation. Assuming that your local repository is up-to-date, you can create a new branch from master. We never make any changes directly to the master branch.

At this point, you leave Git alone and begin working on your changes. You only return to Git after you are done.

When you are done, you add files to the staging area. This is basically a list of files that you would like to commit all at once. Everything outside of the staging area is not committed. When the staging area is properly populated, you can commit. By committing, you are basically declaring that you are confident in your changes, that they form a single cohesive whole, and that they are more-or-less complete.

Sharing your changes

If you did the above, you have now added a commit to a branch in your local repository. But you want to eventually get that commit into the master branch of the main remote repository. To do that, you have to follow a few steps.

First, you upload the branch with commits to your remote repository (origin).

When you go to https://git.fsfe.org/YOURNAME/fsfe-website, your commit should now be visible in its own branch! This is good, because it means that your change is available online, and that others can view it. This also means that the maintainer of the main remote repository can view your changes.

To ask the maintainer to pull your branch into the master branch of the main remote repository, you create a pull request. You do this by navigating to the main webpage the main remote repository and clicking on "Pull Requests". There, you can create a new pull request and specify that you would like the maintainer to update master (main) with NAME-OF-FEATURE (compare). Add a title and a description, and your work is done :-). The maintainer will review your changes and accept them when everything is okay.

Alternative guide with GUI

As aforementioned, the graphical way to create a pull request is not what we prefer because it's harder to help you with. However, we will guide you through the same process as above but it is recommended to try the terminal guide at first because it will probably be easier for you to understand the concept. We are using ´git-cola´, a program which you can find in most distributions.

Set up your repository

Assuming you have set up your remote repository by clicking the "Fork" button on the main project page, you can now set up your local repository.

attachment:clone.png

You are now on the master branch of fsfe-website in your local repository.

Also, by cloning, you have implicitly configured a "remote" for your local repository. This remote is called origin, and is equal to "git@git.fsfe.org:YOURNAME/fsfe-website.git". You might want to add an extra remote, however, pointing to the main remote repository. Let's do this now, and call it upstream.

attachment:remote.png

Your local repository is now tracking two remote repositories, and you are ready to begin working.

Syncing all repositories

Before you start, you may want to synchronise all repositories so that you are working on the latest version of the main remote repository (upstream).

Start on a new feature

Let's begin changing something, e.g. adding a new translation. Assuming that your local repository is up-to-date, you can create a new branch from master. We never make any changes directly to the master branch.

attachment:create.png

At this point, you leave Git alone and begin working on your changes. You only return to Git after you are done.

When you are done, you add files to the staging area. This is basically a list of files that you would like to commit all at once. Everything outside of the staging area is not committed. When the staging area is properly populated, you can commit. By committing, you are basically declaring that you are confident in your changes, that they form a single cohesive whole, and that they are more-or-less complete.

attachment:commit.png

Sharing your changes

If you did the above, you have now added a commit to a branch in your local repository. But you want to eventually get that commit into the master branch of the main remote repository. To do that, you have to follow a few steps.

First, you upload the branch with commits to your remote repository (origin).

attachment:push2.png

When you go to https://git.fsfe.org/YOURNAME/fsfe-website, your commit should now be visible in its own branch! This is good, because it means that your change is available online, and that others can view it. This also means that the maintainer of the main remote repository can view your changes.

To ask the maintainer to pull your branch into the master branch of the main remote repository, you create a pull request. You do this by navigating to the main webpage the main remote repository and clicking on "Pull Requests". There, you can create a new pull request and specify that you would like the maintainer to update master (main) with NAME-OF-FEATURE (compare). Add a title and a description, and your work is done :-). The maintainer will review your changes and accept them when everything is okay.

Miscellaneous tasks

Sections for misc. tasks go here, so they don't litter the main guide with superfluous information.

Questions

This guide is, and will probably always be, incomplete. Git is a very advanced piece of software. If you run into a problem that this guide does not explain, please ask a technically inclined person to add a section to the guide that sufficiently explains how to deal with that problem.

There are also very many guides on how to use Git on the internet. Atlassian and GitHub have some very detailed tutorials that may help you.

TechDocs/Git/Workflow (last edited 2018-04-11 14:17:32 by max.mehl)