team-docs/modules/ROOT/pages/contributing-docs/tools-edit-local-clone.adoc

This guide will show you how to set up a documentation editing environment with a local clone.

Editing locally allows you to make complex edits to multiple pages simultaneously. It also allows you to preview edits exactly as they will appear once published on the main docs site.

Important

This guide deals only with repositories (repos) hosted on Fedora Forge. The process will differ for repos hosted on GitLab, GitHub, or Pagure. You can find the legacy guides for the previously used hosting platforms in the contribution tools section of this website.

For explanations and references on the Fedora Docs tooling, please visit the Contribute to Fedora docs page.

Prerequisites

• First steps section completed.

• Git installed.

• Text editor of choice installed. It is beneficial, but not essential, if your text editor has integrated file navigation, a terminal, and AsciiDoc syntax support.

Set up a local editing environment

1. Create a local subdirectory where your local clone will be stored. The example uses the name "fedora-docs" but you can use any name.

   mkdir ~/fedora-docs
   cd    ~/fedora-docs

2. Use the Forge web interface to fork the repo you intend to edit. Click the Fork button (normally top right).

   

   If prompted, enter the details to create your new fork. The default values are suitable in most cases.

3. Configure your Forge access token and clone your remote fork to your machine. Follow the How to clone a Forge repo using the HTTPS guide to complete this.

4. Configure the upstream repo in your local clone. You will need this to fetch updates from the upstream main docs repo.

   git remote add upstream https://forge.fedoraproject.org/docs/team-docs.git

   Verify it with:

   git remote -v

   The exact URLs may differ. But check that you have two origin entries that match your fork and two upstream entries that match the upstream main docs repo URL. The output should resemble this:

   origin  https://forge.fedoraproject.org/<forge-user-name>/<reponame>.git (fetch)
   origin  https://forge.fedoraproject.org/<forge-user-name>/<reponame>.git (push)
   upstream        https://forge.fedoraproject.org/docs/<reponame>.git (fetch)
   upstream        https://forge.fedoraproject.org/docs/<reponame>.git (push)

   Note	The terms origin and upstream are not strict descriptors but commonly used names to refer to your fork and the upstream fork respectively. So you can choose different names to represent the two repos if you wish.

5. Create a working branch:

   git checkout -b <branch-name-you-choose>

At its most basic level, branching is simply taking a snapshot of the main line of the repo and making changes to that branch. This keeps what you’re working on separate from what others are working on and allows for multiple changes to be merged into the main branch. After you have made your changes to the files and committed those changes to your origin repo, you can then open a pull request to have your changes merged into the main branch and published on the docs site.

You are now ready to start writing.

Consider making use of the Fedora style guide as well as the Vale tool to assist your editing.

Edit the AsciiDoc code with a text editor

Configure your text editor or IDE of choice with the following three viewing windows:

• project folder structure.

• project terminal window open at username@device:~/fedora-docs/name-of-project.

• .adoc file contents window.

The above layout allows you to quickly select files, make edits, and issue git and preview commands, all within the same tool.

Preview your work

1. In the terminal, navigate to your project folder. Type and enter this command:

   ./docsbuilder.sh

   The ./docsbuilder script starts the Antora static site generator locally on your device within an isolated container. There is no requirement to install Antora or any other web development tools on your device.

2. In a browser, visit http://localhost:8080.

3. To update the preview after further edits:

   1. Ensure the script is at rest - the terminal window activity should have stopped and the last sentence read Watching current directory…​.

   2. Save the .adoc file you have been editing and observe the script complete again.

   3. Refresh the browser window.

Pushing your changes to your remote fork in Forge

1. Add the changes to your local git staging ground:

   git add .

2. Commit with a message:

   git commit -m <meaningful-name-reflecting-what-you-changed>

3. Push your changes:

   git push origin <branch-name>

You are now ready to open a pull request (PR).

Opening a PR

PR Checklist

• ❏ Spelling and grammar checked.

• ❏ Metadata and author tags entered.

• ❏ Tested and previewed using the ./docsbuilder script.

Submit the PR

On the Forge web interface, navigate to your fork’s repo and the branch you have been working on. Click on the New Pull Request button.

Some content derived from "Pull requests and Git flow" by Codeberg Docs Contributors.