From Fedora Project Wiki
m (Fix formatting)
Line 20: Line 20:
  
 
# Go to the Pagure repo you want to fork (for example https://pagure.io/fedora-docs/quick-docs/)
 
# Go to the Pagure repo you want to fork (for example https://pagure.io/fedora-docs/quick-docs/)
# Click the **Fork** button at the top.
+
# Click the '''Fork''' button at the top.
  
 
{{admon/note|Forks don't magically stay in sync|You will need to keep your fork up-to-date with the official repo. This is covered later in this document.}}
 
{{admon/note|Forks don't magically stay in sync|You will need to keep your fork up-to-date with the official repo. This is covered later in this document.}}
Line 26: Line 26:
 
This creates a fork under your account (for example https://pagure.io/fork/bcotton/fedora-docs/quick-docs). Now you need to "clone" your forked repo—download it to your computer.
 
This creates a fork under your account (for example https://pagure.io/fork/bcotton/fedora-docs/quick-docs). Now you need to "clone" your forked repo—download it to your computer.
  
# Click the **Clone** drop-down menu in Pagure
+
# Click the '''Clone''' drop-down menu in Pagure
# Copy the contents of the **SSH** box
+
# Copy the contents of the '''SSH''' box
 
# From a terminal, run `git clone <SSH URL>`. For example: `git clone ssh://git@pagure.io/forks/bcotton/fedora-docs/quick-docs.git`
 
# From a terminal, run `git clone <SSH URL>`. For example: `git clone ssh://git@pagure.io/forks/bcotton/fedora-docs/quick-docs.git`
  

Revision as of 13:59, 19 November 2019

Warning.png
This page is a draft only
It is still under construction and content may change. Do not rely on the information on this page. Your contributions are welcome.

Git for docs writers

I have heard from several would-be documentation contributors that they don't know how to effectively use Git to contribute to Fedora documentation. This document attempts to provide some guidance. It is intended to be opinionated to keep from overwhelming the reader.

Prerequisites

To do anything else on this page, you'll want to have the following:

  • A Fedora Account System (FAS) account
  • git (dnf install git)
  • The text editor of your choice
  • Basic terminal experience
  • (recommended) Podman (dnf install podman)

Before your first edit

When you first get started, you won't have commit access to the git repos for docs. You'll need to create your own copy, called a "fork". To do this,

  1. Go to the Pagure repo you want to fork (for example https://pagure.io/fedora-docs/quick-docs/)
  2. Click the Fork button at the top.
Note.png
Forks don't magically stay in sync
You will need to keep your fork up-to-date with the official repo. This is covered later in this document.

This creates a fork under your account (for example https://pagure.io/fork/bcotton/fedora-docs/quick-docs). Now you need to "clone" your forked repo—download it to your computer.

  1. Click the Clone drop-down menu in Pagure
  2. Copy the contents of the SSH box
  3. From a terminal, run git clone <SSH URL>. For example: git clone ssh://git@pagure.io/forks/bcotton/fedora-docs/quick-docs.git
Note.png
Or use a graphical git tool
This document uses the terminal for git commands. However, you may also choose to use a graphical git tool. The principles of the workflow are the same.
Idea.png
Have a dedicated directory
By default, git clone will clone a repository into a subdirectory named the same as the repo that exists in the directory you run the command from. In order to keep your filesystem nice and tidy, you may want to have a dedicated directory that you keep all of your docs repos in. For example: $HOME/fedora/docs

Now here comes the part where you make your life—and the life of the other contributors—a little bit easier. You're going to add the official repo as another "remote" so that you can keep your fork in sync.

  1. From a terminal, run git remote add upstream <UPSTREAM URL>. For example: git remote add upstream https://pagure.io/fedora-docs/quick-docs.git

Before every contribution

Making a contribution

Idea.png
Branches are free
It's better to create a new branch even if you don't need it than to wish later that you had created a branch because you're trying to clean up conflicts. Make branches for even the most trivial contributions and you'll avoid that potential heartbreak.