Skip to content

Latest commit

 

History

History
143 lines (118 loc) · 4.85 KB

CONTRIBUTE.adoc

File metadata and controls

143 lines (118 loc) · 4.85 KB
Raw

Contribution guidelines

Before you suggest automation guidelines, please consider the contribution guidelines layed out in this document.

Writing

  1. The guidelines are written in asciidoc as described by Asciidoctor.

  2. each guideline is made of one sentence, as easy to remember as possible, followed by a collapsible description, made of:

    • explanations

    • rationale

    • examples

      The result looks then as the following template shows (you may copy & paste):

      == Do this and do not do that is the guideline
[%collapsible]
====
Explanations:: These are explanations

Rationale:: This is the rationale

Examples:: These are examples
+
.A mini playbook example
[source,yaml]
----
---
- name: A mini example of playbook
  hosts: all
  gather_facts: false
  become: false
  tasks:
    - name: Say what we all think
      ansible.builtin.debug:
        msg: asciidoctor is {{ my_private_thoughts }}
----
+
Even more examples...
====
      Note
      		 see how it looks like in the [_example] section below.

  3. Those guidelines are grouped into sections and optionally sub-sections, as far as required for maintainability.

  4. Those (sub-)sections can be written in their own source file, but then are included with include::directory/file.adoc[leveloffset=1] in the parent section’s file. This makes sure that all source files are interlinked and can be rendered all together by rendering the top README.adoc, either with asciidoctor or with asciidoctor-pdf.

    Note
    		 this contribution file is obviously not meant for inclusion in the overall document.

  5. Each source file has a single title (the line starting with one equal sign) and can be rendered individually (the leveloffset is set such that it fits in the overall headings structure when included).

  6. The source code is written as readable as possible in its raw form, without impacting maintainability.

  7. We follow the Asciidoc recommended practices.

  8. Sentences are written in the present tense form, avoid "should", "must", etc. For example, "Sentences are written", not "Sentences should be written" or "Sentences must be written". This avoids filler words.

  9. The singular "they" is used to avoid the unreadable "he/she/it" construct and still be neutral.

Contributing

  1. Just fork the repository, create a Pull Request (PR) and offer your changes.

    Tip
    		 limiting each PR to a single recommendation makes it easier to review. This furthermore speeds up approval, which is an advantage also for contributors.

  2. Feel free to review existing PR and give your opinion

  3. Also an issue against one of the recommendations is a valid approach

Example

This is how one guideline as shown above looks like once rendered:

Do this and do not do that is the guideline

Details
Explanations

These are explanations

Rationale

This is the rationale

Examples

These are examples

A mini playbook example
- name: a mini example of playbook
  hosts: all
  gather_facts: false
  become: false

  tasks:

  - name: say what we all think
    debug:
      msg: asciidoctor is {{ my_private_thoughts }}

Even more examples…​

Publish for the website

Use for now the following manual command to publish to the website:

asciidoctor -a toc=left -D docs -o index.html README.adoc
asciidoctor -a toc=left -D docs CONTRIBUTE.adoc
mkdir -p docs/images
cp -v images/*.svg docs/images
Note
 it doesn’t seem that there is any much better way to keep links to images correct according to the HTML generation / managed images chapter.

Creating a PDF

If you run (a current) Fedora Linux, then you can use the Makefile.

  • make view generates both PDF files and displays the GPA guide

  • make print prints to your default printer

  • make spell runs hunspell for spellchecking

  • …

Alternatively, use the following manual commands to generate the 2 PDFs:

asciidoctor-pdf \
  --attribute=gitdate=$(git log -1 --date=short --pretty=format:%cd) \
  --attribute=githash=$(git rev-parse --verify HEAD) \
  --out-file Good_Practices_for_Ansible.pdf \
  README.adoc
asciidoctor-pdf \
  --attribute=gitdate=$(git log -1 --date=short --pretty=format:%cd) \
  --attribute=githash=$(git rev-parse --verify HEAD) \
  --out-file Contributing-to-GPA.pdf \
  CONTRIBUTE.adoc