User:Bcotton/git-for-docs-writers

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.

This is one way, not the only way
The instructions in this document are not the only way to accomplish the goals. In some cases, they may not even be the best way. But they're a way that works. This is targeted explicitly at beginning git users, and so does not include much in the way of choices or options. As the reader gets more familiar with git, I expect them to deviate in ways that work best for them.

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)

Using other operating systems
While this document was written with Fedora in mind, the steps below work on any operating system with git installed. See the git documentation for more information on installing git on other operating systems.

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.

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

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.

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

Before you start making your contributions, you want to make sure you're up-to-date with the upstream repository. This means you are making changes to the latest version.

1. Ensure you're in your master branch with git checkout master
2. Get the upstream changes with git fetch upstream
3. Merge the upstream into your repo with git merge upstream/master

This assumes the repo you're editing uses master as the main branch. Some repositories may have a different workflow. Check with the team if you're not sure.

Making a contribution

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.

Now it's time to make the contribution you came here to make. You'll want to start by creating a new branch to do the work in.

1. git checkout -b branch_name (where branch_name is something like issue8-fix_typos or add_git_tips_for_writers)

Picking a good branch name
You can name a branch whatever you want. Descriptive names are good, especially if it's something you'll be working on over several sessions. If you're working directly on the upstream repo, using a unique and descriptive branch name helps other contributors know what your branch is.

What branch am I in?
You can check your current branch with git branch. Your current branch will have a * at the beginning of the line. If you need to switch to an existing branch, use git checkout branch_name.

Now you can make whatever changes it is that you want. Fire up your favorite text editor and edit away. When you're done, it's time to commit the changes.

1. git add file(s) that you edited
2. git commit
3. Edit the commit message and quit the editor. If your system uses vim as the default editor (which it probably does, unless you changed it), type i to enter editing mode. When you're done writing your commit message, hit the Escape key, type :wq, and hit enter.

Writing good commit messages
Good commit messages are helpful when someone (including future you) looks at the commit history to see what was done. A good commit message says what the commit does and why.

Keep commits atomic
Try to keep your commits related to a single logical change. This makes it easier to undo it if needed. A "single logical change" may require editing multiple files, which should all be in one commit, but if you're adding unrelated content, do it separately.

Finally, it's time to push your changes from your local machine to the remote server and create the pull request.

1. git push origin branch_name
2. In your web browser, go to your forked repo (for example https://pagure.io/fork/bcotton/fedora-docs/quick-docs)
3. Follow the git forge's instructions for creating a pull request (docs for Pagure and GitHub)