egret/team-docs
1
0
Fork 1
forked from docs/team-docs
Code Pull requests Wiki Activity

draft-update2

Browse source
This commit is contained in:
Eli Ridge 2026-05-06 00:35:22 +12:00
commit e107b8ea1c
2 changed files with 19 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

BIN
modules/ROOT/assets/images/fork-button.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 2.2 KiB

36
modules/ROOT/pages/contributing-docs/tools-edit-local-clone.adoc
View file

@ -3,18 +3,18 @@
:page-pagination:
Jocelyn G and Eli R
This guide will show you how to set up a documentation (docs) editing environment with a local clone.
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.
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.
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 explanation and references on the Fedora docs tooling, please visit the https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/[Contribute to Fedora docs] page.
For explanations and references on the Fedora Docs tooling, please visit the https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/[Contribute to Fedora docs] page.
//above links to the live page not the draft of the updated one
@ -23,7 +23,7 @@ For explanation and references on the Fedora docs tooling, please visit the http
* https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/#_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, terminal, and AsciiDoc syntax support.
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
@ -37,10 +37,11 @@ cd ~/fedora-docs
----
2. Use the Forge web interface to fork the repo you intend to edit. Click the Fork button in the top-right corner of the project page:
2. Use the Forge web interface to fork the repo you intend to edit. Click the *Fork* button (normally top right).
+
image here
image::fork-button.png[]
+
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 https://docs.fedoraproject.org/en-US/forge-documentation/using_http_auth/[How to clone a Forge repo using the HTTPS] guide to complete this.
@ -59,8 +60,8 @@ 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 return should resemble this:
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)
@ -70,7 +71,7 @@ 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 indeed choose different names to represent the two different repos if you choose to.
So you can choose different names to represent the two repos if you wish.
5. Create a working branch:
+
@ -81,7 +82,9 @@ git checkout -b <branch-name-you-choose>
//See here for an explanation of branches and why it is best practice to create a working branch/s.
****
At it's most basic form, 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 seperate 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 that you are changing, and have commited those changes to your origin repo, you can then open a pull request to have your changes merged into the main branch to be published on the docs site.
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.
@ -111,6 +114,7 @@ The above layout allows you to quickly select files, make edits, and issue git a
+
****
The ./docsbuilder script starts the Antora static site generator locally on your device within an isolated container.
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.
****
@ -156,11 +160,9 @@ You are now ready to open a pull request (PR)
=== Submit the PR
On the Forge web interface, navigate to your fork's repo and the branch you have been working.
Use the click button to open 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.
****