Contributing to WALLIX Automation Showroom

Thank you for your interest in contributing to the WALLIX Automation Showroom project! This document provides guidelines and instructions for contributing.

Code of Conduct
Getting Started
How to Contribute
Development Workflow
Coding Standards
Testing Guidelines
Documentation
Security

Code of Conduct

This project adheres to a code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

Our Standards

Be respectful and inclusive
Welcome newcomers and help them learn
Accept constructive criticism gracefully
Focus on what is best for the community
Show empathy towards others

Getting Started

Prerequisites

Ansible 2.9+
Python 3.6+
Git
A WALLIX Bastion for testing (or access to one)

Initial Setup

Fork the repository

# Fork on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/Automation_Showroom.git
cd Automation_Showroom/Ansible/Provisioning/Advanced

Add upstream remote

git remote add upstream https://github.com/wallix/Automation_Showroom.git
git fetch upstream

Create development environment

# Install Ansible and dependencies
pip install -r requirements.txt

# Set up test inventory
cp inventory/development.example inventory/development

How to Contribute

Types of Contributions

We welcome:

Bug fixes: Fix issues in existing code
New features: Add new roles, tasks, or playbooks
Documentation: Improve guides, examples, or API docs
Tests: Add or improve test coverage
Examples: Contribute real-world usage examples

Reporting Issues

Before creating an issue:

Check if the issue already exists
Include detailed reproduction steps
Provide environment details (Ansible version, Python version, WALLIX Bastion version)
Include relevant logs (sanitized of sensitive data!)

Suggesting Features

Open an issue with the "enhancement" label
Describe the use case and benefit
Provide examples if possible
Be open to discussion and feedback

Development Workflow

1. Create a Branch

# Update your fork
git checkout develop
git pull upstream develop

# Create feature branch
git checkout -b feature/my-new-feature

# Or for bug fixes
git checkout -b fix/issue-123

Branch Naming Convention

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation changes
test/ - Test additions/changes
refactor/ - Code refactoring

2. Make Changes

Follow our coding standards and:

Write clear, descriptive commit messages
Keep commits focused and atomic
Test your changes thoroughly
Update documentation as needed

3. Commit Your Changes

# Stage changes
git add .

# Commit with descriptive message
git commit -m "feat: add support for RADIUS authentication

- Implement RADIUS authentication in wallix-domains role
- Add configuration examples
- Update documentation
- Add tests for RADIUS auth"

Commit Message Format

<type>: <subject>

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation only
test: Adding tests
refactor: Code refactoring
style: Code style changes (formatting)
chore: Maintenance tasks

4. Push and Create Pull Request

# Push to your fork
git push origin feature/my-new-feature

# Create PR on GitHub

Pull Request Guidelines

Title: Clear and descriptive
Description: Explain what and why
Link issues: Reference related issues
Screenshots: Include if UI/output changes
Testing: Describe how you tested
Checklist: Complete the PR template checklist

Coding Standards

Ansible Playbook Standards

YAML Formatting

---
# Always start with document separator
- name: Descriptive task name
  module_name:
    parameter: value
    another_parameter: value
  when: condition
  tags:
    - tag1
    - tag2

Best Practices

Always name tasks

- name: Create user account
  # Good

- user:
  # Bad - no name

Use YAML dictionary format

# Good
- name: Create directory
  file:
    path: /etc/wallix
    state: directory
    mode: '0755'

# Avoid
- name: Create directory
  file: path=/etc/wallix state=directory mode=0755

Idempotency
- All tasks should be idempotent
- Running twice should be safe
- Use changed_when and failed_when appropriately
Variables
- Use meaningful names: wallix_api_host not host
- Prefix role variables: rolename_variable
- Use snake_case for variables
Security
- Never hardcode credentials
- Always use Ansible Vault for secrets
- Use no_log: true for sensitive tasks

Role Structure

roles/wallix-component/
├── defaults/
│   └── main.yml          # Default variables
├── tasks/
│   └── main.yml          # Main tasks
├── handlers/
│   └── main.yml          # Handlers
├── templates/
│   └── config.j2         # Jinja2 templates
├── files/
│   └── script.sh         # Static files
├── vars/
│   └── main.yml          # Role variables
├── meta/
│   └── main.yml          # Role metadata
└── README.md             # Role documentation

Python Code Standards

Follow PEP 8:

# Good
def calculate_api_timeout(base_timeout, retry_count):
    """Calculate total API timeout including retries."""
    return base_timeout * (retry_count + 1)

# Include docstrings
# Use descriptive names
# Follow 4-space indentation

Documentation Standards

Markdown

Use ATX-style headers (# not underlines)
Include table of contents for long docs
Use code blocks with language specified
Include examples liberally

Comments

# Explain WHY, not WHAT
- name: Retry API call on network failures
  # The bastion may be behind a load balancer causing intermittent failures
  uri:
    url: "{{ wallix_api_url }}"
  retries: 3

Testing Guidelines

Before Submitting

Syntax check

ansible-playbook --syntax-check playbooks/your-playbook.yml

Dry run

ansible-playbook -i inventory/development playbooks/your-playbook.yml \
  --check

Test in development

ansible-playbook -i inventory/development playbooks/your-playbook.yml

Test Coverage

Test all new features
Test edge cases
Test error handling
Verify idempotency

Test Environments

Development: For initial testing
Staging: For integration testing
Production: For final validation (with caution!)

Documentation

What to Document

New features: How to use them
API changes: Breaking changes especially
Configuration: New variables or settings
Examples: Real-world usage
Troubleshooting: Common issues

Where to Document

README.md: Overview and getting started
QUICKSTART.md: Quick setup guide
Role README: Specific role documentation
Code comments: Complex logic
CHANGELOG.md: Version changes

Documentation Checklist

Security

Security-First Approach

Never commit secrets
- Check .gitignore is comprehensive
- Use Ansible Vault for all credentials
- Scan commits before pushing
Sanitize examples
- Use placeholders: example.com, 192.0.2.1
- No real IPs or hostnames
- Obvious fake credentials
Report security issues privately
- Don't create public issues
- Wait for security advisory

Security Checklist

Review Process

What Reviewers Look For

Functionality: Does it work?
Code quality: Follows standards?
Tests: Adequately tested?
Documentation: Well documented?
Security: No vulnerabilities?
Compatibility: Works with supported versions?

Responding to Feedback

Be open to suggestions
Ask questions if unclear
Make requested changes promptly
Thank reviewers for their time

Changelog

Update CHANGELOG.md:

## [1.2.0] - 2025-10-03

### Added
- RADIUS authentication support in wallix-domains role

### Changed
- Improved error handling in wallix-auth role

### Fixed
- Session cleanup now properly removes temporary files

Getting Help

Communication Channels

GitHub Issues: Bug reports and features
Pull Requests: Code discussions

Resources

Recognition

Contributors will be recognized in:

CONTRIBUTORS.md file
Release notes
Project documentation
README.md contributors section (via all-contributors)

Adding Contributors with all-contributors

This project uses all-contributors to recognize all contributors, not just code contributors.

Adding a New Contributor

Method 1: Using the all-contributors bot (Recommended)

Comment on an issue or pull request:

@all-contributors please add @username for code, doc, example

Available contribution types:

code: Code contributions
doc: Documentation
example: Examples
test: Tests
ideas: Ideas & planning
infra: Infrastructure (CI/CD, build tools)
maintenance: Maintenance
review: Reviewing pull requests
question: Answering questions
bug: Bug reports
talk: Talks/presentations
tutorial: Tutorials

Method 2: Using the CLI

# Add a contributor
npx all-contributors add username code,doc

# Generate the contributors list
npx all-contributors generate

Method 3: Manual editing

Edit .all-contributorsrc:

{
"contributors": [
   {
      "login": "username",
      "name": "Full Name",
      "avatar_url": "https://avatars.githubusercontent.com/u/12345",
      "profile": "https://github.com/username",
      "contributions": [
      "code",
      "doc"
      ]
   }
]
}

Generate the table:
```
npx all-contributors generate
```

Commit the changes:

git add .all-contributorsrc README.md
git commit -m "docs: add @username as a contributor"

Contribution Types Guide

Choose the appropriate types for the contribution:

Type	When to Use
`code`	Any code contributions (playbooks, roles, scripts)
`doc`	Documentation improvements (README, guides, comments)
`example`	Adding or improving examples
`test`	Adding or improving tests
`ideas`	Feature suggestions, architecture discussions
`infra`	CI/CD, GitHub Actions, build scripts
`review`	Reviewing PRs, providing feedback
`bug`	Filing detailed bug reports
`question`	Helping others in issues/discussions

Note: Contributors are automatically added when their PR is merged if using the all-contributors bot.

Thank you for contributing! 🎉

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History