Ansible repository files and settings

Creating a new repository

In most cases, you should use the ansible-community/project-template when creating a new repository. Using the project-template populates the new repository with recommended content such as license, DCO, and code of conduct.

If required, you can move over content and contributor history from a source repository into your new repository. An alternative might be to use the GitHub importer at https://github.com/new/import to create a new repo that preserves contributor history and all content from the original source repo.

The GitHub importer allows you to basically mirror a repository without forking it. You can then add and remove content as needed. However if there is a need to change the license or other essential files, it's better to use the project-template. This way you have the correct license from the initial commit.

Preserving contributor history

When moving content from one repository to another, it is important to preserve contributor history. This section outlines some general techniques for moving git revision history.

There are many different strategies and options to achieve this, depending on your goals. In some cases, you might want to preserve the entire chain of commits. For larger repositories with years of history, you might want to preserve only portions of the commit chain to prevent bloating the new repository.

Merging unrelated histories

A straightforward method of moving contributor history is to add the source repository as a remote of the new repository and then merge the history.

# Clone the new repository and add the source as a remote.
git clone git@github.com:org/new-repo.git
git remote add source-repo git@github.com:org/source-repo.git

# Confirm that the source is a remote.
git remote -v
origin	git@github.com:org/new-repo.git (fetch)
origin	git@github.com:org/new-repo.git (push)
source-repo	git@github.com:org/source-repo.git (fetch)
source-repo	git@github.com:org/source-repo.git (push)

# View the history of the new repository.
# You should see the initial commit and any subsequent commits as you'd expect.
git log

# Fetch the content of the source repository.
git fetch source-repo

# Merge the main or devel branch of the source repository into the new repository.
git merge source-repo/main --allow-unrelated-histories

# If you encounter any conflicts you'll need to fix them and then continue the merge.
git merge --continue

# At this point the new repository should contain the contributor history from the source repository.
# Viewing the history again should show the merge commit on top, the initial commit, and then the commit history.
git log

# You can view the history of individual files or directories.
git log --follow path/to/directory_or_file

# Move and delete files that were merged from the source repository as needed.
git mv path/to/directory_or_file
git rm -rf directory
git commit

# Push the changes to the new repository.
git push origin HEAD:main

Exporting and copying the source repository

Another option is to get a clean export of the git history from the source repository and then copy it to the new repository. This option might be suitable when the new repository does not have any commits yet.

# Create a bare clone with the main or devel branch.
# A bare clone is essentially just the .git directory of the repository.
git clone --branch=main --bare git@github.com:org/source-repo.git

# Change to the directory of the bare clone.
cd source-repo.git

# Push the main branch of the source repository to the main branch of the new repository.
git push git@github.com:org/new-repo.git HEAD:main

GitHub settings for Ansible projects

Teams can make their own informed choices on project conventions and code related configuration like *.toml files. This section highlights some initial GitHub settings that might be useful for new Ansible projects.

Branch ruleset

Enforcement status: Active
Branch targeting criteria: All branches
Branch rules:

Restrict deletions
Require signed commits
Require a pull request before merging
Required approvals = 2
Require approval of the most recent reviewable push
Require conversation resolution before merging
Block force pushes

Features

Ansible projects should use the forum for discussions and help queries. Likewise, Ansible projects should provide actively maintained docsites hosted on Read The Docs.

Disable Wikis
Disable Discussions

Pull request merge settings

Merge commits can result in cluttered git history. On the other hand, merge commits are useful, especially in cases when merging a series of related commits that you later want to cherry-pick separately.

Starting out with a new repository it can be beneficial to disable merge commits and squash only while changes occur more frequently. However this is generally a matter of preference and ultimately for teams to discuss and decide amongst themselves.

Disable Allow merge commits
Enable Allow squash merging (default)
Enable Allow rebase merging (default)

Code scanning and analysis

Here is a basic rundown of the static analysis and code scanning tools for Ansible project repositories. For help with these tools, use the Red Hat internal slack channel, #ansible-github-admins.

SonarCloud

Projects in the Ansible GitHub org have access to SonarCloud static analysis tooling. PRs will have comments from Sonarcloud detailing the analysis of the delta in the subject PR, and a passing scan will be required for the final merge.

You can configure SonarCloud analysis using a properties file in your repo, see Additional analysis configuration.

To get set up with SonarCloud or ask questions, use the Red Hat internal slack channel #wg-aap-sonarcloud.

Pre-commit ci

Pre-commit ci is a tool that automatically fixes trivial issues and problems in pull requests, like code formatting.

https://github.com/apps/pre-commit-ci/installations/19541297

Codecov

Codecov is a recommended tool for quality gates and ensuring test coverage for PRs.

https://github.com/apps/codecov/installations/398480

Ansible project docsite

Ansible projects should provide docsites with markdown or RST source files.

Use the Ansible theme

Use either the MKDocs or Sphinx theme:

Add docsite to the `ansible` namespace

Ansible projects that are managed by Red Hat should be available under the ansible namespace in Read The Docs. To do this, your project needs to be added as a subproject to https://readthedocs.org/projects/ansible/

If you do not have access to the ansible project, you can ping one of the maintainers like Don Naro, Sviat, Shane, gundalow, or Sandra McCann.

Enable PR previews

Be sure to enable PR previews in Read The Docs, see How to configure pull request builds.