To contribute to this project we have best practices, rules and guidelines to follow.
We aim to publish all code under the terms of the GPL in public repositories. Sometimes we want to keep things internal and mark repositories as “private”, but this the exception and not the norm.
We’re using GitLab to manage our source code, write documentation and track progress.
All work is tracked in the GitLab Issue Tracker. Use the repository specific issues if a problem or feature is directly related to a repository. If it’s not possible to have such a direct relationship, create the issue in the parent project. When start working on an issue, assign it to yourself so others can see that someone is working on it.
Merge Requests can only be created if they reference an existing issue. Merge Requests should link back to the issue by using GitLab feature to close issues automatically. Don’t forget to use the Work in Progress flag to let others know things are not completely done.
Use labels to make it easier to find issues and filter for issue categories:
Feature Request: Propose an idea to be added (use color code #69D100)
Bug: Something doesn’t work and needs fixing (use color code #FF0000)
Documentation: update or add something to the documentation in the pages project (use color code ##6699cc)
Newbie: easy to implement and low risk of breaking something (use color code #D1D100)
The labels are not pre-populated on all projects and if missing will be created on their first use.
Projects can use additional labels when needed.
We’re using a variant of Git Flow when developing content for this project.
‘main’ is always the latest development version. We never break ‘main’! Development is done in a separate branch and merged into ‘main’ after passing all tests.
The release branch is forked from ‘main’ and contains the latest stable release. Releases are tagged. We follow Semantic Versioning for assigning release tags. We do not have a release schedule yet, new releases are created when we see fit.
New features are branched from ‘main’ into feature branches. When a feature is complete it is merged back into main by using a Merge Request. Merge Requests can only be opened from an issue. While work on a Merge Request is not completed, it should have an WIP or draft flag.
To make sure we do not accidentally release broken code, the ‘main’ and ‘release’ branches are protected branches.
Only maintainers can push to and merge protected branches, Code Owner approval is not required.
All documentation is done in Markdown in the pages repository. Unlike other code repositories, we do not follow the Git Flow approach for documentation. The ‘main’ branch always contains the latest published version of the documentation. However, we still create branches and Merge Requests to track larger or complex changes. If a repository contains a README.md it will automatically render in the Projects section. If there is a HOWTO.md it will render in the use cases section.
The documentation is published by using GitLab Pages and built automatically from a CI/CD pipeline using Hugo and the learn theme.
THere are several different areas of documentation which is written for different target audiences:
User Guide: This is not a “How to learn Ansible” course, so we assume you know the basics to run Ansible Playbooks, the concepts of Red Hat Ansible Automation Platform and how to use it. We do however explain more advanced features of Ansible or automation controller or relatively new concepts and approaches. We assume you know Linux, Windows, Networking, how to write simple Ansible Playbooks and the automation controller User Interface.
Developer Guide: This is written for experienced Ansible and Git users. We assume you know your way around those tools and will not describe any basics. We assume you can write complex Ansible Playbooks, Roles, Collections, can interact with automation controller by using modules, the CLI or the REST API. We also assume you know git, know how to write nice playbooks, are familiar with the Ansible best practices, ansible-lint, etc.