the-common / ansible-project-template

A sensible Ansible project template for initializing a new project.

The common Ansible project template

A sensible Ansible project template for initializing a new project.

https://gitlab.com/the-common/ansible-project-template

How to use

If you're on GitLab

1. Create a new project via the on-site interface, it is required to check the "Initialize repository with a README" checkbox.

2. At localhost, launch a text terminal application, and run the following commands to clone the new project's repository to local:

   git clone \
       _repository_url_ \
       _project_directory_

3. Downloading a copy of The common Ansible project template release archive

4. Extract The common Ansible project template release archive to a temporary directory

5. Copy all the files to the new project local repository's working tree

6. Continue the operation in Common instructions

If you're on GitHub

1. Click the "Use this template" green button on the mirrored GitHub project page
2. Follow the instructions on the webpage to create a new project
3. Continue the operation in Common instructions

Common instructions

1. Edit the real.README.md project README template, replace the following `placeholders to the appropriate content:

   • _project_name_
   • _project_summary_
   • _namespace_/_project_
     Part of the project URLs, you use another project hosting service you need to manually replace the entire URLs instead
   • _license_name_
   • _license_url_

   Also remove the unused To be addressed sections

2. Replace the SPDX-FileCopyrightText and the SPDX-License-Identifier fields of the REUSE.toml machine-readable copyright declaration document with appropriate content.

3. Run the following commands(or its equivalent operation) to remove the template-only custom license:

   find_opts=(
       -type f
       -exec
           sed
               --in-place
               --regexp-extended
               --expression='s@ OR LicenseRef-Apache-2.0-If-Not-Used-In-Template-Projects@@g'
               {}
               ';'
   )
   find . "${find_opts[@]}"

4. Replace .markdownlint.yml with real.markdownlint.yml

5. Replace README.md(this document) with real.README.md

6. Customize/remove Telegram notification details in .github/workflows/check-potential-problems.yml

7. Commit all changes as a new revision(commit summary for reference: docs: Write project README prototype)

8. (If you've cloned the repository back to local) push local changes to the remote repository

Licensing

Unless otherwise noted(individual file's header/REUSE.toml), this product is licensed under the 4.0 International version of the Creative Commons Attribution-ShareAlike license, or any of its more recent versions of your preference.

As an exception of the previous clause, this product can be licensed otherwise under the 2.0 version of the Apache license if it is used to instantiate/refactor a project based on it rather than using it in the making of another template project. This allows relicensing the project assets to your liking in your non-template projects with only a conformance requirement of attributing this product somewhere in your project/product credits/acknowledgment/copyright notice documentation/user interface.

This work complies to the REUSE Specification, refer the REUSE - Make licensing easy for everyone website for info regarding the licensing of this product.