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,
- 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.
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.
- Click the Clone drop-down menu in Pagure
- 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
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.
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/docsNow 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.
- 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
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.