Setting up a local authoring environment

The Fedora Server Edition working group, Peter Boy (pboy), Stephen Daley (mowest) Last review: 2023-04-23

Fedora Server documentation is at: https://pagure.io/fedora-server/.

It includes the content as well as various scripts to build and preview the site locally. The directory structure is predefined by the docs Content Management System (Andorra) and must not be changed.

It has 2 permanent branches: "main" for the published content and "stg" for planning, development, and discussion. Temporarily, additional branches may also be present.

For up- and download you can use either https or ssh. For people with FAS account ssh may be more convenient.

The workflow folllow the Fedora docs project "[https://docs.fedoraproject.org/en-US/fedora-docs/contributing/git/ Git for docs writers]". Each contributor should create a fork of the repository for themselves. Contributions are uploaded to the fork and then transferred to the authoritative version via a pull request. This opens up the possibility for others to comment and initiate a broader discussion.

Writing tools

You can use any ASCII editor to work on the documentation files.

A particularly useful OSS Asciidoc editor is AsciidocFX. It is a Java program, very easy to install, and provides both an integrated directory access, a toolbar with the most common AsciiDoc formatting similar to a Word editor and an integrated instant preview.

Creating a new documentation article

An annotated template is available to make things easier. Download it and save it in the appropriate directory with a new name.

If possible, the files should be named in such a way that related files appear together in the directory listing. The most important, most differentiating parts should be at the front. For example

  • filesharing-nfs-administration.adoc

  • filesharing-nfs-installation.adoc

  • filesharing-samba-administration.adoc

  • filesharing-samba-installation.adoc

The titles should follow this pattern as far as possible and avoid redundant parts such as "How to install …​"

  • File sharing with NFS - Installation

  • File sharing with NFS - Administration

  • File sharing using Samba - Installation

  • File sharing using Samba - Administration

All file names are in lower case.

Preparations

  1. Create a local subdirectory where the files of the documentation should be stored, and make it your default. We use fedora-server-docs in your home directory throughout this guide

    […]$ mkdir ~/fedora-server-docs
[…]$ cd    ~/fedora-server-docs

  2. Still in your default working directory, clone fedora-server repository

    […]$ git clone https://git@pagure.io/fedora-server.git -o upstream

    Git will copy the complete server repo including all branches, specifically "main" and "stg" mentioned above, into a local repo on your local workstation (into .git/ located in your default directory).

    Git does "tag" the cloned repo as remote repo "upstream".

    At the same time it checks out the default branch "''main''" into your ''working directory'' (i.e. ~/fedora-server-docs in the above example). Therefore, when the operation terminates, you will find in your current default directory, which is now your ''working directory'', some files, e.g. README.md, docsbuilder.sh and preview.sh and a directory docs. The latter contains the content.

    If you leave off "./" at the end, git creates another directory in your default directory with the name of the repository, i.e. fedora-server. And this directory is then the "working directory" to the repository. This can be useful if you want to keep track of different fedora docs projects in one directory.

  3. In your browser go to https://pagure.io/fedora-server/, log in and create a Fork. Once you have done it, the button will read View fork. Switch to your fork and click on Clone and you will see 2 addresses you can use to clone (copy) the content to your local default directory

    ssh://git@pagure.io/forks/[MY_FAS]/fedora-server.git
https://git@pagure.io/forks/[MY_FAS]/fedora-server.git

    Still in your default working directory, add the forked Repo to your remote repos.

    […]$ git remote add origin ssh://git@pagure.io/forks/[MY_FAS]/fedora-server.git

    You can use https as well. For users with a FAS account ssh is usually the better choice.

  4. You have now 2 remote repos defined. Check:

    […]$ git remote -v
origin	ssh://git@pagure.io/forks/[MY_FAS]/fedora-server.git (fetch)
origin	ssh://git@pagure.io/forks/[MY_FAS]/fedora-server.git (push)
upstream	https://git@pagure.io/fedora-server.git (fetch)
upstream	https://git@pagure.io/fedora-server.git (push)

    In your workflow you will update your local version to the latest versions of the server repository by "pulling" the content from "upstream" and upload your modifications and additions by "pushing" it to origin, i.e. to your fork. You will than create a "pull request", i.e. pick up your modifications and additions from your fork and integrate it into the generic repository ("origin"). This enables co-writers to review our work and comment on it.

  5. In your working directory build the local version and start the preview tool.

    […]$ ./docsbuilder.sh

  6. Back in your browser enter the local preview address': localhost:8080

    • You should see a local preview of the current Server documentation

Working on content

  1. Check if you are on the branch you intend to work on

    […]$ git branch
main
* stg

  2. If not, switch to the branch you want to use.

    […]$ git checkout [stg|main]

    Git will adjust and modify the content of your working directory accordingly!

  3. Before your begin to work update your working directory

    […]$ git commit -m "<YOUR COMMIT MESSAGE>"

  4. Modify content

  5. Update preview and check:

    […]$ ./docsbuilder.sh

    Preview in your browser using the address 'localhost:8080

  6. Repeat step 4 & 5 as required.

Save Your Work

Commit your work locally and then push it into your fork "origin".

  1. Check status

    […]$ git status

  2. Add files to commit stage as appropriate

    […]$ git add <FILENAME>

  3. Commit locally

    […]$ git commit -m "<YOUR COMMIT MESSAGE>"

  4. Transfer your fork of fedora server to the repository

    […]$ git push origin [main|stg]

  5. In your browser open https://pagure.io/fedora-server, login, switch to your fork and create a pull request.

Want to help? Learn how to contribute to Fedora Docs ›