Server/Documentation/How To Contribute

Authors should be able to contribute to Fedora Server documentation with as little effort as possible and without technical hurdles. We provide several ways to contribute.

1. You may send us an email, e.g. while reading a document on our Web pages.
2. You may download a document, make changes and send it back.
3. You may create a complete authoring environment using Git and Podman / Docker

Sending an e-mail with proposed changes

A very simple and straightforward approach is indicated when something catches your eye while reading an article, or when you are conducting a review of a single document. Just write your suggestions in the form of "current version" - "proposed version" in an email and send it either to the Fedora Server list, server@lists.fedoraproject.org, or directly to the server documentation coordinator (currently pboy@fedoraproject.org). Suggestions will then be included in the text, or perhaps there will be follow-up questions.

Download a document

If the suggested changes are more extensive or consist of very short elements, e.g. typo corrections, it is probably easier to download that one document from our server and change it.

The repository base address is https://pagure.io/fedora-server.

To download a published version, go to the "Files" tab in the left navigation column, then to docs and further along the directory tree to pages. Check the browser address field. It should contain main near the base address. Select the appropriate document file.

To download a not yet published version, go to the "Branches" tab in the left navigation column. In the "stg" row select the left most icon "code tree for this branch". The file list then displayed contains a stg at the top. Follow the directory tree under docs to the pages directory. Check the browser address field. It should contain blob/stg near the base address. Select the appropriate document file.

"Right click" onto the RAW button and select "Save Link As ..." (Firefox). In the dialog that opens, save the file to a suitable location on your workstation.

You can edit the document using any text editor. For convenience you should use an asciidoc editor. We recommend AsciidocFX (https://asciidocfx.com). It is quite slim yet sophisticated, and available for all operating systems. The editor includes a preview, which of course can only be an approximation due to the lack of site-specific CSS, but contains the essential elements.

After completion of the editing send the file by email directly to the server documentation coordinator (currently pboy@fedoraproject.org).

Setting up an authoring environment

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 „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.

Preparations

1. Create a local subdirectory where the files of the documentation should be stored, and make it to your default. We use fedora-server-docs in your home 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, build.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 requuest“, 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 create the built und preview: […]$ ./build.sh && ./preview.sh

6. Back to 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 to 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:

   […]$ ./build.sh && ./preview.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 to your fork of fedora server 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.