local-workflow-update #58
jflory7
pboy
theprogram
korora
venefilyn
cstrauf
Labels
No labels
effort
high
effort
low
effort
medium
good first issue
help wanted
meeting topic
needs changes
needs reporter feedback
needs review
priority
high
priority
low
priority
medium
priority
on hold
type/content
type/misc
No milestone
No project
No assignees
4 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
docs/team-docs!58
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "egret/team-docs:local-docscontrib"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
PR for #14.
See: docs/tickets#14
@ -0,0 +1,203 @@= Edit Documentation Using a Local Workflow:revdate: 2026-04-01:page-pagination:Jocelyn G and Eli RYou could note FAS usernames here so it would be easier for a contributor to reach out to the page authors, but it is not a critical thing.
@ -0,0 +26,4 @@In Fedora Linux, you can check that _git_ is installed by running the following command:+----$ dnf install gitI don't know if we have a style rule for this, but since the docs site theme makes it easy to copy and paste from blocks, I always prefer having the shebang absent so I am not pasting the
$into my command line when copy-pasting things.Super small nitpick though.
We actually have a rule, or more precisely a guide: Typographic style guide.
@ -0,0 +49,4 @@+image::fork-button.png[]+If prompted, enter the details to create your new fork. The default values are suitable in most cases.https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line
@ -0,0 +123,4 @@The _docsbuilder_ script uses Podman to build a preview of your docs pages in an isolated container.. In the terminal, navigate to your project folder. Run the _docsbuilder_ script by entering this command:https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line
@ -0,0 +144,4 @@.. Save the .adoc file you have been editing and observe the script complete again... Refresh the browser window.NOTE: On MacOS, the _docsbuilder_ script uses Docker instead of Podman. You can install Docker from the official https://www.docker.com/[Docker Website].https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line
@ -0,0 +184,4 @@* [ ] Metadata and author tags entered.* [ ] Tested and previewed using the ./docsbuilder script.s/docsbuilder/docsbuilder.sh/@ -0,0 +200,4 @@Podman is an open source container tool similar to Docker.When you run the docsbuilder.sh script, Podman will download the Antora parser to your local machine as a container.Once you are done with the container, if you wish to remove it, simply run ``podman image rm antora``.There is no harm in leaving the container on your system if you are working on a lot of docs. This will allow you to save some bandwidth on the hosting server for the image.https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line
@ -3,6 +3,8 @@ Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs-team>:revdate: 2024-08-30:page-pagination:IMPORTANT: Many of the repositories have now been migrated to https://forge.fedoraproject.org[Fedora Forge]. See the updated xref:contributing-docs/tools-file-edit-forge.adoc[Edit from a local clone] guide.https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line
On the whole, the changes look great to me. Marking as approved, but perhaps @pbokoc should make an official review before merging.
I made a few nitpicks in individual comments, but they are all minor things.
Also, I suggest a squash commit as the merge strategy for this PR.
@ -0,0 +1,209 @@= Edit Documentation Using a Local WorkflowThe title is really clunky. How about "Edit documentation locally"?
@ -0,0 +5,4 @@This guide will show you how to set up a local documentation editing environment on your computer, using a local clone.****The
****creates this weird box in the rendered page that we don't use anywhere else. I'd suggest leaving this as a standard paragraph, or a[NOTE]in the following format:This happens multiple times throughout the PR and I don't want to open a new note for each occurence. Please go through both the adoc files, search for
****, and change them all.@ -0,0 +10,4 @@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.This should be formatted as
It renders the same but this is the convention we usually go with.
This happens multiple times throughout the PR and I don't want to open a new note for each occurence. Please go through the whole file, search for
NOTEandIMPORTANT, and change them all to blocks like indicated above.@ -0,0 +14,4 @@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 xref:contributing-docs/index.adoc [Contribute to Fedora docs] page.No spaces between the link URL and
[link text]@ -0,0 +40,4 @@+[source,console]----mkdir ~/fedora-docsAdd the
$prompt to commands to differentiate between them and output (if there is any).This applies to the whole PR, there's a bunch of cases.
@ -0,0 +59,4 @@4. Configure the upstream repo in your local clone.You will need this to fetch updates from the upstream main docs repo.+----Add
[source,console]to the line above to make sure it renders the same as other examples.Applies to the whole PR - please go through the whole thing and add it everywhere it's missing, I don't want to copypaste this everywhere.
I really like it overall! I added some notes but apart from one it's just style changes.
@ -3,6 +3,9 @@ Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs-team>:revdate: 2024-08-30:page-pagination:IMPORTANT: Many of the repositories have now been migrated to https://forge.fedoraproject.org[Fedora Forge].Missed this one :P