An Ansible role for installing Apache2, enabling/disabling modules, configuring its defaults and creating virtual hosts.
Below you can find information on…
-
the role’s required Ansible version
-
the role’s supported platforms
-
the role’s role dependencies
---
galaxy_info:
role_name: "apache2"
description:
"An ansible role for installing Apache2, enabling/disabling modules,
configuring its defaults and creating virtual hosts.
Based on geerlingguy's apache2 role. "
author: "jonaspammer"
license: "MIT"
min_ansible_version: "2.11"
platforms:
# note: text after "actively tested: " represent the docker image name
- name: EL # (Enterprise Linux)
versions:
- "9" # actively tested: rockylinux9
- name: Fedora
versions:
- "38" # actively tested: fedora38
- "39" # actively tested: fedora39
- name: Debian
versions:
- bullseye # actively tested: debian11
- bookworm # actively tested: debian12
- name: Ubuntu
versions:
- focal # actively tested: ubuntu2004
- jammy # actively tested: ubuntu2204
galaxy_tags:
- web
- apache
- webserver
- html
- httpd
dependencies: []
allow_duplicates: trueThe Ansible User needs to be able to become.
If you are using SSL/TLS ([apache_vhosts_ssl]), you will need to provide your own certificate and key files.
If you are using Apache with PHP, I recommend using the
geerlingguy.php role
to install PHP, and you can either use mod_php
(by adding the proper package, e.g. libapache2-mod-php5 for Ubuntu, to php_packages),
or by also using
geerlingguy.apache-php-fpm
to connect Apache to PHP via FPM.
Please consult the README’s of the linked roles for more specific information.
When targeting Solaris-based systems,
the community.general collection
(containing the pkg5 module) must be installed on the Ansible controller.
When targeting Suse-based systems,
community.general collection
(containing the zypper module) must be installed on the Ansible controller.
apache_mods_enabled:
- rewrite
- ssl
apache_mods_disabled: [](Debian/RHEL only)
Apache mods to enable or disable (these will be symlinked into the appropriate location).
Consult the mods-available (Debian) / conf.modules.d (RHEL) directory inside apache’s root directory for all the available mods.
apache_listen_ip: "*"
apache_listen_port: 80
apache_listen_port_ssl: 443The IP address and ports on which apache should be listening. Useful if you have another service (like a reverse proxy) listening on port 80 or 443 and need to change the defaults.
apache_remove_default_vhost: falseOn Debian/Ubuntu, a default virtualhost is included in Apache’s configuration.
Set this to true to remove that default.
apache_state: startedSet initial apache state.
Recommended values: started or stopped
apache_enabled: trueSet initial apache service status.
Recommended values: true or false
apache_restart_state: restartedSets the state to put apache in when a configuration change was made
(i.e., when the restart apache handler has been called).
Recommended values: restarted or reloaded
apache_default_favicon: favicon.icoPath to a file on the local Ansible Controller to be copied to the server and used by Apache as a default favicon.
apache_packages: [OS-specific by default, see /defaults directory]A list of package names for installing Apache2 and most-necessary utilities.
apache_packages_state: presentIf you have enabled any additional repositories such as
ondrej/apache2,
EPEL, or
remi,
you may want an easy way to upgrade versions.
To ensure so, set this to latest.
apache_enablerepo: ""(RHEL/CentOS only)
The repository
to use when installing Apache.
If you’d like later versions of Apache than are available in the OS’s core repositories,
use a repository like
EPEL
(which can be installed with the repo-epel role).
|
Tip
|
Head over to the 📚 Example Playbook Usages-Section for examples showing how the produced VirtualHost-File may look like. |
|
Note
|
This role tries to ensure a working apache configuration by running
syntax tests for all configuration files ( |
apache_create_vhosts: true
apache_vhosts_filename: "vhosts.conf"
apache_vhosts_template: "vhosts.conf.j2"If set to true, a vhosts file managed by the variables of this role (see below),
is created and placed in the Apache configuration folder.
If set to false, you can place your own vhosts file into Apache’s configuration folder and skip the convenient (but more basic) one added by this role.
You can also override the template used and set a path to your own template, if you need to further customize the layout of your VirtualHost.
apache_global_vhost_settings: |
DirectoryIndex index.php index.htmlThis variable gets used outside any <VirtualHost> Directive in the generated virtualhost file.
|
Warning
|
You hereby change the configurations applied to Apache’s general context
(instead of changing the configurations applied to, for example, a A thing to understand with this default value is that
the
|
apache_vhosts:
- servername: "local.dev"
documentroot: "/var/www/html"For each entry in this list,
a <VirtualHost>-Directive listening to
{{ apache_listen_ip }}:{{ apache_listen_port }}
will be generated.
Each entry of a list may have the following properties (Consult the 📚 Example Playbook Usages-Section for Examples. Consult the linked official documentation pages for the documentation of the actual Apache Directives they represent).
servername(required)serveraliasserveradmindocumentrootdocumentroot__allowoverride-
AllowOverride-Directive used inside the<Directory>of theDocumentRoot.
Defaults to the value ofapache_vhosts_default_documentroot__allowoverride. documentroot__options-
Options-Directive used inside the<Directory>of theDocumentRoot.
Defaults to the value ofapache_vhosts_default_documentroot__options. logformatloglevel
errorlog-
Either a string (representing the path. does not get automatically quoted) or a complex data type:
path-
Path. Gets enquoted in
". extra-
Additional String to append after
path. extra_parameters-
This variable gets inserted as-is before the actual
ErrorLogstatement (with an indent of 2).The use case for this parameter may be to enable Conditional Logs using
SetEnvIf/SetEnvor setting a customLogFormatfor this ErrorLog Apache’s core Documentation.
customlogs-
Array of CustomLogs. Each Entry may either be a string (does not get automatically quoted) or a complex data type:
path-
Path. Gets enquoted in
". extra-
Additional String to append after
path. Does not get quoted (to allow for the complex additional optional parameters of CustomLog one may want to supply). extra_parameters-
This variable gets inserted as-is before the actual
CustomLogstatement (with an indent of 2).The use case for this parameter may be to enable Conditional Logs using
SetEnvIf/SetEnvor setting a customLogFormatfor this specifc CustomLog as per Apache’s mod_log_config Documentation.
extra_parameters-
This variable gets inserted as-is into the very end of the looped
<VirtualHost>(with an indent of 2).
apache_vhosts_ssl: []For each entry in this list,
a <VirtualHost>-Directive listening to
{{ apache_listen_ip }}:{{ apache_listen_port_ssl }}
will be generated.
Each entry of a list may have the following properties (Consult the 📚 Example Playbook Usages-Section for Examples) (Consult the linked official documentation pages for the documentation of the actual Apache Directives they represent).
servername(required)serveraliasserveradmindocumentrootdocumentroot__allowoverride-
AllowOverride-Directive used inside the<Directory>of theDocumentRoot.
Defaults toapache_vhosts_default_documentroot__allowoverride. documentroot__options-
Options-Directive used inside the<Directory>of theDocumentRoot. Defaults toapache_vhosts_default_documentroot__options. no_actual_ssl-
If set to True, the
<VirtualHost>will have no SSL* Options. Used only when you want a http-to-https redirect you defined inextra_parameters. - ssl_certificate_file (required)
- ssl_certificate_key_file (required)
- ssl_certificate_chain_file
-
Please note that this Deprecated.
logformatloglevelerrorlog-
Equivalent of apache_vhosts.errorlog.
customlogs-
Array of CustomLogs. Equivalent of apache_vhosts.customlogs.
extra_parameters-
This variable gets inserted as-is into the very end of the looped
<VirtualHost>(with an indent of 2).
apache_ignore_missing_ssl_certificate: trueIf set to false, a given entry of apache_vhosts_ssl
will only be generated if its sslcertificatefile exists.
apache_ssl_protocol: "All -SSLv2 -SSLv3"
apache_ssl_cipher_suite: "AES256+EECDH:AES256+EDH"These variable are used as default for every apache_vhosts_ssl.
They are named the same way as used in said Role variables
(except for their prefix of course).
Consult
Apache’s Documentation
for the documentation of the actual Apache Directives they represent.
apache_vhosts_default_documentroot__allowoverride: "All"
apache_vhosts_default_documentroot__options: "-Indexes +FollowSymLinks"Each variable listed in this section
is dynamically defined when executing this role (and can only be overwritten using ansible.builtin.set_facts) and
is meant to be used not just internally.
apache__service# handlers file for roles.xyz
- name: restart apache2
ansible.builtin.service:
name: "{{ apache__service | default('apache2') }}"
state: restartedapache__daemon_dir, apache__daemonExecutable Name and Directory of the apache2 command.
apache__server_root_dirDirectory containing all Apache2 configuration (in /etc).
|
Note
|
When working with any of the below configuration values you need to remember:
— Comment found in a Debian 10's /etc/apache2/apache2.conf
This means that the tree /etc/apache2 of a fresh Debian 10 machine after apache2 install.
├── apache2.conf
├── conf-available
│ ├── charset.conf
│ ├── localized-error-pages.conf
│ ├── other-vhosts-access-log.conf
│ ├── php7.4-fpm.conf
│ ├── security.conf
│ └── serve-cgi-bin.conf
├── conf-enabled
│ ├── charset.conf -> ../conf-available/charset.conf
│ └── …
├── envvars
├── magic
├── mods-available
│ ├── access_compat.load
│ ├── alias.load
│ ├── alias.conf
│ └── …
├── mods-enabled
│ ├── access_compat.load -> ../mods-available/access_compat.load
│ ├── alias.conf -> ../mods-available/alias.conf
│ ├── alias.load -> ../mods-available/alias.load
│ └── …
├── ports.conf
├── sites-available
│ ├── 000-default.conf
│ └── default-ssl.conf
└── sites-enabled
└── 000-default.conf -> ../sites-available/000-default.conf
While on other systems it looks like this: tree /etc/apache2 of a fresh CentOS 8 machine after apache2 install. ├── conf │ ├── httpd.conf │ └── magic ├── conf.d │ ├── autoindex.conf │ ├── ssl.conf │ ├── userdir.conf │ └── welcome.conf ├── conf.modules.d │ ├── 00-base.conf │ ├── 00-dav.conf │ ├── 00-lua.conf │ ├── 00-mpm.conf │ ├── 00-optional.conf │ ├── 00-proxy.conf │ ├── 00-ssl.conf │ ├── 00-systemd.conf │ ├── 01-cgi.conf │ ├── 10-h2.conf │ ├── 10-proxy_h2.conf │ └── README ├── logs -> ../../var/log/httpd │ └── … └── modules -> ../../usr/lib64/httpd/modules ├── mod_access_compat.so ├── mod_actions.so ├── mod_alias.so └── … |
apache__primary_configuration_file_pathApache2’s primary configuration file,
which
Include's all the other files and contains some other Directives itself.
|
Tip
|
Taking a look into how what is Include’ed
Debian’s Apache2 Include Directives as found in # Include module configuration:
IncludeOptional mods-enabled/*.load
IncludeOptional mods-enabled/*.conf
# Include list of ports to listen on
Include ports.conf
# Include of directories ignores editors' and dpkg's backup files,
# Include generic snippets of statements
IncludeOptional conf-enabled/*.conf
# Include the virtual host configurations:
IncludeOptional sites-enabled/*.confRHEL’s Apache2 Include Directives as found in # Dynamic Shared Object (DSO) Support
#
# To be able to use the functionality of a module which was built as a DSO you
# have to place corresponding `LoadModule' lines at this location so the
# directives contained in it are actually available _before_ they are used.
# Statically compiled modules (those listed by `httpd -l') do not need
# to be loaded here.
#
# Example:
# LoadModule foo_module modules/mod_foo.so
Include conf.modules.d/*.conf
# Supplemental configuration:
IncludeOptional conf.d/*.conf |
apache__ports_configuration_fileApache2 Configuration File that houses the directives used to determine listening ports for incoming connections.
On some systems this is the same as apache__primary_configuration_file_path,
but on some it is an own file which is being
Include-ed by said apache__primary_configuration_file_path.
apache__server_conf_dirDirectory which houses all
Include-ed files.
This directory may not be Include-ed itself but have sub-directories that are being Include-ed.
Consult the NOTE/TIP found in apache__primary_configuration_file_path
to know what Directories are being Include-ed by default on different OS’es.
apache__default_log_dirDirectory in /var used by default for all virtual hosts.
The below output shows the typical default file contents of this folder for the major distros:
[root@instance-py3-ansible-5 /]# ls -l /var/log/httpd/ total 8 -rw-r--r-- 1 root root 0 Jun 11 11:16 access_log -rw-r--r-- 1 root root 980 Jun 11 11:16 error_log -rw-r--r-- 1 root root 0 Jun 11 11:16 ssl_access_log -rw-r--r-- 1 root root 328 Jun 11 11:16 ssl_error_log -rw-r--r-- 1 root root 0 Jun 11 11:16 ssl_request_log
root@instance-py3-ansible-5-debian10:/# ls -l /var/log/apache2 total 4 -rw-r----- 1 root adm 0 Aug 29 10:17 access.log -rw-r----- 1 root adm 2133 Aug 29 10:18 error.log -rw-r--r-- 1 root root 0 Aug 29 10:18 local2-error.log -rw-r----- 1 root adm 0 Aug 29 10:17 other_vhosts_access.log
Tasks are tagged with the following tags:
| Tag | Purpose |
|---|---|
This role does not have officially documented tags yet. |
|
You can use Ansible to skip tasks, or only run certain tasks by using these tags. By default, all tasks are run when no tags are specified.
|
Note
|
This role is part of many compatible purpose-specific roles of mine. The machine needs to be prepared.
In CI, this is done in ---
- name: prepare
hosts: all
become: true
gather_facts: false
roles:
- role: jonaspammer.bootstrap
# - name: jonaspammer.core_dependenciesThe following diagram is a compilation of the "soft dependencies" of this role as well as the recursive tree of their soft dependencies.
|
-
The following yaml:
roles: - role: jonaspammer.apache2
generates the following VirtualHost:
# Ansible managed DirectoryIndex index.php index.html <VirtualHost *:80> ServerName local.dev DocumentRoot "/var/www/html" <Directory "/var/www/html"> AllowOverride All Options -Indexes +FollowSymLinks Require all granted </Directory> </VirtualHost>For Reference, this is the default vhost shipped with Debian/Ubuntu systems (which can be removed by setting
apache_remove_default_vhostto true)<VirtualHost *:80> ServerAdmin webmaster@localhost DocumentRoot /var/www/html ErrorLog ${APACHE_LOG_DIR}/error.log CustomLog ${APACHE_LOG_DIR}/access.log combined </VirtualHost>
Given no role configuration, the deviance’s from just installing Apache2 yourself are
-
certain modules get activated by default (
[apache_mods_enabled]). -
the system will have the above demonstrated VirtualHost
-
On initial install, a file with the name of
favicon.ico(sourced from [apache_default_favicon]) will be placed into/var/www/htmlif there was no file with said name before. This favicon, by default, resembles the Ansible logo as found on Wikimedia.
Please note that this role does not delete the contents of /var/www/html
(not even if it got created by/after apache2 initial install).
-
The following yaml:
roles: - role: jonaspammer.apache2 vars: apache_vhost_filename: "local2.dev.conf" apache_vhosts: - servername: "wwww.local2.dev" loglevel: info errorlog: "{{ apache__default_log_dir }}/local2-error.log" customlog: path: "${{ apache__default_log_dir }}/local2-access.log" extra: "combined"
generates the following VirtualHost:
# Ansible managed. TODO
extra_parameters|
Tip
|
The pipe symbol at the end of a line in YAML signifies that any indented text that follows should be interpreted as a multi-line scalar value. See yaml-multiline.info for interactive explanation. |
-
The following yaml:
roles: - role: jonaspammer.apache2 vars: apache_vhost_filename: "myvhost.conf" apache_vhosts: - servername: "www.local.dev" serveralias: "local.dev" documentroot: "/var/www/html" extra_parameters: | # Redirect all requests to 'www' subdomain. Apache 2.4+ RewriteEngine On RewriteCond %{HTTP_HOST} !^www\. [NC] RewriteRule ^(.*)$ %{REQUEST_SCHEME}://www.%{HTTP_HOST}%{REQUEST_URI} [R=302,L]
generates the following VirtualHost:
# Ansible managed. TODO -
The following yaml:
roles: - role: jonaspammer.apache2 vars: apache_vhost_filename: "myvhost.conf" apache_vhosts: - servername: "srvcmk.intra.jonaspammer.com" extra_parameters: | Redirect / {{ checkmk_site_url }}
generates the following VirtualHost:
# Ansible managed. DirectoryIndex index.php index.html <VirtualHost *:80> ServerName srvcmk.intra.jonaspammer.com Redirect / http://srvcmk.intra.jonaspammer.at/master </VirtualHost>
The apache2 role may be executed multiple times in a play, with the primary purpose of this allowance being to be able to create virtualhosts.
- tasks:
#...
- name: Generate Apache2 VirtualHost.
ansible.builtin.include_role: "apache2"
vars:
apache_vhost_filename: "myapp.conf"
apache_vhosts:
- servername: "www.myapp.dev"
serveralias: "myapp.dev"
DocumentRoot: "/opt/myapp"
#...A role may work on different distributions, like Red Hat Enterprise Linux (RHEL), even though there is no test for this exact distribution.
| OS Family | Distribution | Distribution Release Date | Distribution End of Life | Accompanying Docker Image |
|---|---|---|---|---|
Rocky |
Rocky Linux 8 (RHEL/CentOS 8 in disguise) |
2021-06 |
2029-05 |
|
Rocky |
Rocky Linux 9 |
2022-07 |
2032-05 |
|
RedHat |
Fedora 39 |
2023-11 |
2024-12 |
|
Debian |
Ubuntu 20.04 LTS |
2021-04 |
2025-04 |
|
Debian |
Ubuntu 22.04 LTS |
2022-04 |
2027-04 |
|
Debian |
Debian 11 |
2021-08 |
2024-06 (2026-06 LTS) |
|
Debian |
Debian 12 |
2023-06 |
2026-06 (2028-06 LTS) |
|
The tested ansible versions try to stay equivalent with the
support pattern of Ansible’s community.general collection.
As of writing this is:
-
2.13 (Ansible 6)
-
2.14 (Ansible 7)
-
2.15 (Ansible 8)
-
2.16 (Ansible 9)
Development Dependencies are defined in a
pip requirements file
named requirements-dev.txt.
Example Installation Instructions for Linux are shown below:
# "optional": create a python virtualenv and activate it for the current shell session $ python3 -m venv venv $ source venv/bin/activate $ python3 -m pip install -r requirements-dev.txt
Please take a look at my Ansible Role Development Guidelines.
If interested, I’ve also written down some General Ansible Role Development (Best) Practices.
Versions are defined using Tags, which in turn are recognized and used by Ansible Galaxy.
Versions must not start with v.
When a new tag is pushed,
a GitHub CI workflow
(
)
takes care of importing the role to my Ansible Galaxy Account.
Automatic Tests are run on each Contribution using GitHub Workflows.
The Tests primarily resolve around running Molecule on a varying set of linux distributions and using various ansible versions.
The molecule test also includes a step which lints all ansible playbooks using
ansible-lint
to check for best practices and behaviour that could potentially be improved.
To run the tests, simply run tox on the command line.
You can pass an optional environment variable to define the distribution of the
Docker container that will be spun up by molecule:
$ MOLECULE_DISTRO=ubuntu2204 tox
For a list of possible values fed to MOLECULE_DISTRO,
take a look at the matrix defined in .github/workflows/ci.yml.
-
Run your molecule tests with the option
MOLECULE_DESTROY=never, e.g.:$ MOLECULE_DESTROY=never MOLECULE_DISTRO=ubuntu1604 tox -e py3-ansible-5 ... TASK [ansible-role-pip : (redacted).] ************************ failed: [instance-py3-ansible-9] => changed=false ... ___________________________________ summary ____________________________________ pre-commit: commands succeeded ERROR: py3-ansible-9: commands failed
-
Find out the name of the molecule-provisioned docker container:
$ docker ps 30e9b8d59cdf geerlingguy/docker-debian12-ansible:latest "/lib/systemd/systemd" 8 minutes ago Up 8 minutes instance-py3-ansible-9
-
Get into a bash Shell of the container, and do your debugging:
$ docker exec -it 30e9b8d59cdf /bin/bash root@instance-py3-ansible-2:/#
TipIf the failure you try to debug is part of your
verify.ymlstep and not the actualconverge.yml, you may want to know that the output of ansible’s modules (vars), hosts (hostvars) and environment variables have been stored into files on both the provisioner and inside the docker machine under: */var/tmp/vars.yml(contains host variables under thehostvarskey) */var/tmp/environment.ymlgrep,cator transfer these as you wish!TipYou may also want to know that the files mentioned in the admonition above are attached to the GitHub CI Artifacts of a given Workflow run.
This allows one to check the difference between runs and thus help in debugging what caused the bit-rot or failure in general.
-
After you finished your debugging, exit it and destroy the container:
root@instance-py3-ansible-2:/# exit $ docker stop 30e9b8d59cdf $ docker container rm 30e9b8d59cdf or $ docker container prune
Although a standard feature in tox 3, this now only happens when tox recognizes the presence of a CI variable. For example:
$ CI=true tox
This Project offers a definition for a "1-Click Containerized Development Environment".
This Container even enables one to run docker containers inside of it (Docker-In-Docker, dind), allowing for molecule execution.
To use it:
-
Ensure you fullfill the the System requirements of Visual Studio Code Development Containers, optionally following the Installation-Section of the linked page section.
This includes: Installing Docker, Installing Visual Studio Code itself, and Installing the necessary Extension. -
Clone the project to your machine
-
Open the folder of the repo in Visual Studio Code (File - Open Folder…).
-
If you get a prompt at the lower right corner informing you about the presence of the devcontainer definition, you can press the accompanying button to enter it. Otherwise, you can also execute the Visual Studio Command
Remote-Containers: Open Folder in Containeryourself (View - Command Palette → type in the mentioned command).
|
Tip
|
I recommend using |
|
Note
|
You may need to configure your host system to enable the container to use your SSH/GPG Keys. The procedure is described in the official devcontainer docs under "Sharing Git credentials with your container". |
This Project shall be kept in sync with the CookieCutter it was originally templated from using cruft (if possible) or manual alteration (if needed) to the best extend possible.
cruft update
General Linting and Styling Conventions are
automatically held up to Standards
by various pre-commit hooks, at least to some extend.
Automatic Execution of pre-commit is done on each Contribution using
pre-commit.ci*.
Pull Requests even automatically get fixed by the same tool,
at least by hooks that automatically alter files.
|
Note
|
Not to confuse: Although some pre-commit hooks may be able to warn you about script-analyzed flaws in syntax or even code to some extend (for which reason pre-commit’s hooks are part of the test suite), pre-commit itself does not run any real Test Suites. For Information on Testing, see 🧪 Testing. |
|
Tip
|
Nevertheless, I recommend you to integrate pre-commit into your local development workflow yourself. This can be done by cd’ing into the directory of your cloned project and running You can also, for example, execute pre-commit’s hooks at any time by running |
The following sections are generic in nature and are used to help new contributors. The actual "Development Documentation" of this project is found under 📝 Development.
First off, thank you for considering contributing to this Project.
Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests.
This Project owns many of its files to the CookieCutter it was originally templated from.
Please check if the edit you have in mind is actually applicable to the template and if so make an appropriate change there instead. Your change may also be applicable partly to the template as well as partly to something specific to this project, in which case you would be creating multiple PRs.
A casual contributor does not have to worry about following the spec by definition, as pull requests are being squash merged into one commit in the project. Only core contributors, i.e. those with rights to push to this project’s branches, must follow it (e.g. to allow for automatic version determination and changelog generation to work).
Contributions are made to this repo via Issues and Pull Requests (PRs). A few general guidelines that cover both:
-
Search for existing Issues and PRs before creating your own.
-
If you’ve never contributed before, see the first timer’s guide on Auth0’s blog for resources and tips on how to get started.
Issues should be used to report problems, request a new feature, or to discuss potential changes before a PR is created. When you create a new Issue, a template will be loaded that will guide you through collecting and providing the information we need to investigate.
If you find an Issue that addresses the problem you’re having, please add your own reproduction information to the existing issue rather than creating a new one. Adding a reaction can also help be indicating to our maintainers that a particular problem is affecting more than just the reporter.
PRs to this Project are always welcome and can be a quick way to get your fix or improvement slated for the next release. In general, PRs should:
-
Only fix/add the functionality in question OR address wide-spread whitespace/style issues, not both.
-
Add unit or integration tests for fixed or changed functionality (if a test suite already exists).
-
Address a single concern
-
Include documentation in the repo
-
Be accompanied by a complete Pull Request template (loaded automatically when a PR is created).
For changes that address core functionality or would require breaking changes (e.g. a major release), it’s best to open an Issue to discuss your proposal first.
In general, we follow the "fork-and-pull" Git workflow
-
Fork the repository to your own Github account
-
Clone the project to your machine
-
Create a branch locally with a succinct but descriptive name
-
Commit changes to the branch
-
Following any formatting and testing guidelines specific to this repo
-
Push changes to your fork
-
Open a PR in our repository and follow the PR template so that we can efficiently review the changes.
Please refer to the Release Page of this Repository for a human changelog of the corresponding Tags (Versions) of this Project.
Note that this Project adheres to Semantic Versioning. Please report any accidental breaking changes of a minor version update.
MIT License Copyright (c) 2022, Jonas Pammer Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.