Skip to content

Latest commit

 

History

History
261 lines (244 loc) · 11.6 KB

CONTRIBUTING.md

File metadata and controls

261 lines (244 loc) · 11.6 KB

1. How can I contribute?

First, please read the Linux From Scratch Editor's Manual as it contains some good info. Some info is missing and some is LFS-specific.

2. Basics

This project is primarily written in Docbook XML. Most issues and updates pertain to the XML that gets put into the final text of the rendered book. If you wish to contribute somehow but don't know XML and/or don't want to write any XML, you can make issues over on issues.

If you are feeling more savvy, familarize yourself with the book, how it's written, where essential files are located, then make an update as you see fit, and make a PR. This bit requires a more in-depth explanation and where it really diverges from the LFS Editor's Manual. If you are a BLFS editor, editing this book will not be too different. Read sections 3.1.2, 3.2, and 3.3 for LFS QOL specific information.

3. For the savvy

3.1. Where things are located

3.1.1. Internal files and directories

Before starting with the main bulk of the book and what people will be reading, we need to cover the files and directories of the source of the book that are more internal but nonetheless essential.

At the root of the source, you'll find these files and directories:

  • .github/workflows/
  • archive/
  • contributor-tools/
  • images/
  • kernel-config/
  • patches/
  • stylesheets/
  • template/
  • xincludes/
  • .gitattributes
  • .gitignore
  • INSTALL.md
  • Makefile
  • expand_date
  • general.ent
  • generate-doc-stub.py
  • git-version.sh
  • gnome.ent
  • obfuscate.sh
  • packages.ent
  • tidy.conf

3.1.1.1. .github/workflows/

This directory contains YAML files that are used by Github CIs to render the book and put it up on the LFS QOL website hosted on Github. It rarely needs updating.

3.1.1.2. archive/

This directory contains XML files that are no longer considered needed or useful to be included in the book, but are moved there in case they need to be brought back or for the sake of study. Files that don't conform to new standards don't need to be updated unless they are being brought back into the book.

3.1.1.3. contributor-tools/

This directory contains various tools useful when contributing to LFS-QOL. Currently it only contains docstubgen, which is a Python script that generates baseline package contents for a given package, useful when adding a new package to the book. It does not provide actual explanations of a given program or library, but it does list out all the software as necessary to make it easier for contributors. Update as needed if the script is faulty.

3.1.1.4. images/

This directory contains images used by the book, ie. for the note, important, warning, and tip boxes, as well as for the favicon and image that shows up at the top of the home page. Rarely needs to get updated.

3.1.1.5. kernel-config/

This directory contains the needed files to generate kernel configuration blocks you'd find in pages the require you to change the configuration in your kernel. Update as needed.

3.1.1.6. patches/

This directory contains patches used in the book, as well as older patches for historical purposes, in case someone needs the older patches, and for the sake of study. Update as needed and should keep up with newer versions, but old versions must also stay.

3.1.1.7. stylesheets/

This directory contains the Docbook XML XSLT stylesheets needed to generate HTML from the XML source. It also contains the CSS files needed to make the book look prettier. Very rarely needs updating.

3.1.1.8. template/

This directory contains templates that most pages in this book are based on, mainly packages. It has documentation that can help you figure out what you want and don't want. May need to get updated if standards change.

3.1.1.9. xincludes/

This directory contains XML files that are included by several XML files to save repeating text. Same idea as C header files, except these XML files also define what text is to be included. Update as needed.

3.1.1.10. .gitattributes

This file is a standard git file that gives attributes to matching files. Rarely needs to get updated.

3.1.1.11. .gitignore

This file is a standard git file that ignores matching files from entering the git history and tree. For instance, conditional.ent and version.ent generated by git-version.sh are ignored but may exist locally if you render the book. Very rarely needs to get updated.

3.1.1.12. INSTALL.md

This file details what packages you will need in order to render the book yourself. Rarely needs to get updated.

3.1.1.13. Makefile

This file is the Makefile used by make in order to render the book. Rarely needs to get updated.

3.1.1.14. expand_date

This file is a Python script that expands the date variable in XML files, although this behavior has fallen out of favor in LFS QOL but remains strong in BLFS. Rarely needs to get updated.

3.1.1.15. general.ent

This file is an XML entity file containing important variables used by the book's XML and also includes different entity files. This file needs to get updated every stable release.

3.1.1.16. generate-doc-stub.py

This symlink points to contributor-tools/docstubgen/docstubgen, whose purpose has already been described above in section 3.1.1.3.

3.1.1.17. git-version.sh

This file is a shell script that generates the version and revision the book should be rendered for, and outputs according text to conditional.ent and version.ent. Rarely needs to get updated.

3.1.1.18. gnome.ent

This file is an XML entity file that contains GNOME specific entities used by a small selection of XML files. Rarely needs to get updated.

3.1.1.19. obfuscate.sh

This file is a shell script that obfuscates email addresses in XML and HTML files. Rarely needs to get updated.

3.1.1.20. packages.ent

This file is an XML entity file that contains version variables. Certain version variables are used by certain packages, although usually there will only be one variable used by a given package. For example, &hyprutils-version; is used by hyprutils. These variables determine the package's version. Whenever a package needs an update, this file needs to get edited.

3.1.1.21. tidy.conf

This file is a configuration file used by tidy. Rarely needs to get updated.

3.1.2. Book files and directories

Now that the internals are covered, it's time to cover the files that have a stronger impact of the final rendered product. Here are the following files and directories at the root of the source:

  • appendices/
  • binary/
  • book/
  • emu/
  • gen-game/
  • general/
  • introduction/
  • svr4/
  • wm/
  • changelog.xml (link to introduction/welcome/changelog.xml)
  • index.xml

Some packages in the directories may need to get updated whenever a version gets updated. Unlike BLFS, LFS QOL does not use md5sums, SBUs, or size. It does use links and package versions, however. The links have to be correct, as well as the instructions.

3.1.2.1. appendices/

This directory contains XML files rendered at the end of the book. Rarely needs to get updated.

3.1.2.2. binary/

This directory contains XML files rendered for the Binary Support part. Contains packages.

3.1.2.3. book/

This directory contains XML files rendered at the beginning of the book. Rarely needs to get updated.

3.1.2.4. emu/

This directory contains XML files rendered for the Emulators part. Contains packages.

3.1.2.5. gen-game/

This directory contains XML files rendered for the General Gaming Software part. Contains packages.

3.1.2.6. general/

This directory contains XML files rendered for the General Libraries and Utilities part. Contains packages.

3.1.2.7. introduction/

This directory contains XML files rendered for the Introduction part of the book. Contains welcome/changelog.xml which does need to get updated often. Rest of the XML files usually don't.

3.1.2.8. svr4/

This directory contains XML files rendered for the SVR4 part of the book. Contains packages.

3.1.2.9. wm/

This directory contains XML files rendered for the Window Managers, Compositors, and Desktop Environments part. Contains packages.

3.1.2.10. changelog.xml

This symlink points to introduction/welcome/changelog.xml, an XML file that details changes made to the book since the last release. All changes should be noted here, and the message should be similar or exact to the git commit message that details the commit. -> should be -> in the XML file. For the user in the changelog entry, it'd be appreciated if it matched with your Github username. If you are a BLFS/LFS editor, you can also use the handle you use for LFS/BLFS. Changes that shouldn't have a changelog entry are simple typos, grammar changes, fixing rendering failures, wording, etc. (small changes) and internal changes (not counting changes to packages.ent, those count as updates that need to have a changelog entry).

3.1.2.11. index.xml

This file is an XML file that determines which main XML files to include for rendering. Think of it as the master XML file, or your int main(), but for XML. Rarely needs changing unless a new section is added.

3.1.3. Standards

Beyond knowing where files are, the text inside those files also counts, and there are standards to keep in mind.

  1. No tabs except in the Makefile. Use spaces. Unless after a sentence, use two at a time.
  2. Keep character count on any given line a maximum of 80 characters and do not go over that limit. This keeps the XML from getting ugly and out of hand. There are situations where you can't keep it under that limit, such as using links or code blocks. That is fine. But if you can help it, please keep under the 80 character limit.
  3. Use oxford commas (subject1, subject2, and subject3) instead of (subject1, subject2 and subject3).
  4. Edit changelog.xml as necessary. See section 3.1.2.9.

3.2. Making an update

First, you're going to need Git in order to clone, pull, and push. Once you have it installed, you are going to need to fork this repository to your Github account. Once you have it forked, you are going to need to clone that fork:

git clone https://github.com/<username>/lfs-qol

Now that you have cloned the repo, you can make changes to the default branch trunk, or you can make another one:

git checkout --track origin -b <branch_name>

Now make an edit as you see fit. If it isn't an edit to an internal file that isn't packages.ent or fixing a simple typo, make a changelog entry (see section 3.1.2.9). Once you have made one, copy the text you made, reformat that text you copied into plain text that won't get messed up in a git commit message, then do a test render. See if the render looks fine, if it rendered. Afterwards, do a git status to see you edited the correct files, haven't made any new ones that shouldn't have been made, then git add those files. Afterwards, do

git commit -m "<copied_text>" -m "<optional_message>"

Now do:

git push origin <branch_name>

3.3. Making a PR

Now over on Github on your repo, make a Pull/Merge Request that merges into glfs-book:trunk. If it has a conflict, repeat section 3.2. to fix those conflicts before making the PR/MR. If all looks good, submit it.

There may be changes requested. This is okay and is routine. Repeat section 3.2. as necessary and Github will automatically pull in the new changes to the PR. Rinse and repeat until the PR is merged.

After that, pat yourself on the back, as you are now a LFS QOL contributor.