|
|
| Line 1: |
Line 1: |
| {{draft|Your contributions are welcome.}} | | {{fedoradocs: https://docs.fedoraproject.org/en-US/fedora-docs/contributing/git/}} |
| | |
| = 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.
| |
| | |
| {{admon/tip|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 [[Account_System|Fedora Account System]] (FAS) account
| |
| * git (`dnf install git`)
| |
| * The text editor of your choice
| |
| * Basic terminal experience
| |
| * (recommended) Podman (`dnf install podman`)
| |
| | |
| {{admon/tip|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 [https://git-scm.com/book/en/v2/Getting-Started-Installing-Git 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".
| |
| | |
| {{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/tip|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`}}
| |
| | |
| # Go to the upstream Pagure repo
| |
| ## Click the '''Clone''' drop-down menu in Pagure
| |
| ## Copy the contents of the '''Git''' box
| |
| ## From a terminal, go to the directory you want to keep your repository in. For example `cd $HOME/fedora/docs`. You will need to create this directory if it doesn't exist (for example: `mkdir -p $HOME/fedora/docs`)
| |
| ## From a terminal, run `git clone <GIT URL> -o upstream`. For example `git clone https://pagure.io/fedora-docs/quick-docs/ -o upstream`.
| |
| # Create your forked Pagure repo
| |
| ## Go to the Pagure repo you want to fork (for example https://pagure.io/fedora-docs/quick-docs/). We will refer to this as the ''upstream'' repo from now on.
| |
| ## Click the '''Fork''' button at the top.
| |
| ## Click the '''Clone''' drop-down menu in Pagure
| |
| ## Copy the contents of the '''SSH''' box
| |
| # Add your fork to the local checkout
| |
| ## From a terminal, go to the directory you cloned above. (For example: `cd $HOME/fedora/docs/quick-docs`)
| |
| ## From a terminal, run `git remote add origin <SSH URL>`. For example: `git remote add origin ssh://git@pagure.io/forks/bcotton/fedora-docs/quick-docs.git`)
| |
| | |
| {{admon/note|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.}}
| |
| | |
| == 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.
| |
| | |
| # Ensure you're in your master branch with `git checkout master`
| |
| # Get the upstream changes with `git pull`
| |
| | |
| {{admon/note|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.}}
| |
| | |
| {{admon/tip|Keep your fork up-to-date|If you use the web view of your forked repo, you will want to push the updated content to your fork. Do this with `git push origin master`.}}
| |
| | |
| == Making a contribution ==
| |
| | |
| {{admon/tip|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.
| |
| | |
| # `git checkout -b ''branch_name''` (where ''branch_name'' is something like `issue8-fix_typos` or `add_git_tips_for_writers`)
| |
| | |
| {{admon/tip|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.}}
| |
| | |
| {{admon/tip|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.
| |
| | |
| # `git add ''file(s) that you edited''`
| |
| # `git commit`
| |
| # 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.
| |
| | |
| {{admon/tip|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.}}
| |
| | |
| {{admon/tip|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.
| |
| | |
| # `git push origin ''branch_name''`
| |
| # In your web browser, go to your forked repo (for example https://pagure.io/fork/bcotton/fedora-docs/quick-docs)
| |
| # Follow the git forge's instructions for creating a pull request (docs for [https://docs.pagure.org/pagure/usage/pull_requests.html Pagure] and [https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork GitHub])
| |
