Setting up a local authoring envireonment

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.

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.

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