Contributing to ProbatioVault Infrastructure¶

Thank you for your interest in contributing to the ProbatioVault infrastructure project! This document provides guidelines and instructions for contributing.

Table of Contents¶

• Code of Conduct
• Getting Started
• Development Workflow
• Contribution Guidelines
• Testing
• Documentation
• Commit Messages
• Pull Request Process

Code of Conduct¶

Our Pledge¶

We are committed to providing a welcoming and inclusive environment for all contributors, regardless of experience level, background, or identity.

Our Standards¶

• Be respectful and considerate in all interactions
• Be collaborative and open to constructive feedback
• Be professional and focus on technical merits
• Be patient with new contributors learning the codebase

Unacceptable Behavior¶

• Harassment, discrimination, or offensive comments
• Personal attacks or trolling
• Publishing private information without consent
• Any conduct that would be inappropriate in a professional setting

Getting Started¶

Prerequisites¶

Before contributing, ensure you have:

1. Development tools installed:

# Terraform
brew install terraform  # macOS

# Ansible
brew install ansible    # macOS

# Git
brew install git

1. Access to development environment:
2. SSH access to a test VPS (not production)
3. GitLab account with access to the repository

4. Basic understanding of Infrastructure as Code principles

5. Read the documentation:

6. README.md - Project overview
7. Architecture - Architecture details
8. Deployment Quickstart - Setup guide

Setting Up Your Development Environment¶

1. Fork and clone the repository:

git clone https://gitlab.com/yourusername/probatiovault-infra.git
cd probatiovault-infra

1. Create a feature branch:

git checkout -b feature/your-feature-name

1. Verify Terraform configuration:

cd terraform
terraform init
terraform validate

1. Verify Ansible syntax:

cd ../ansible
ansible-playbook playbook.yml --syntax-check

Development Workflow¶

Branch Naming Convention¶

Use descriptive branch names:

• feature/add-monitoring - New features
• fix/postgresql-backup - Bug fixes
• docs/update-quickstart - Documentation updates
• refactor/ansible-roles - Code refactoring
• test/gitlab-runner - Testing improvements

Making Changes¶

1. Terraform changes:
2. Update .tf files in terraform/
3. Run terraform fmt to format code
4. Run terraform validate to check syntax

5. Update relevant .tfvars examples

6. Ansible changes:

7. Update roles in ansible/roles/
8. Use YAML best practices (2-space indentation)
9. Run ansible-lint if available

10. Test on a non-production VPS

11. Documentation changes:

12. Update relevant .md files
13. Ensure markdown is properly formatted
14. Include examples where appropriate

Code Style Guidelines¶

Terraform¶

# Use consistent naming
variable "vps_name" {
  description = "Clear description of the variable"
  type        = string
  default     = "sensible-default"
}

# Group related resources
resource "null_resource" "vps_reference" {
  # Use comments to explain non-obvious logic
  triggers = {
    vps_name = var.vps_name
  }
}

Ansible¶

---
# Use descriptive task names
- name: Install PostgreSQL server
  apt:
    name: postgresql
    state: present
    update_cache: yes

# Use variables for flexibility
- name: Configure PostgreSQL
  template:
    src: postgresql.conf.j2
    dest: "/etc/postgresql/{{ postgresql_version }}/main/postgresql.conf"
  notify: restart postgresql

Documentation¶

• Use clear, concise language
• Include code examples
• Add command outputs where helpful
• Use proper markdown formatting
• Keep line length reasonable (80-120 chars)

Contribution Guidelines¶

What to Contribute¶

We welcome contributions in these areas:

1. Bug fixes - Fix issues in existing code
2. New features - Add new Ansible roles, Terraform modules
3. Documentation - Improve or add documentation
4. Testing - Add tests, improve CI/CD
5. Performance - Optimize existing code
6. Security - Enhance security measures

What NOT to Contribute (Without Discussion)¶

• Major architectural changes
• Breaking changes to existing APIs
• Removal of existing features
• Changes to core security policies

For major changes, please open an issue first to discuss the proposal.

Testing¶

Testing Terraform Changes¶

cd terraform

# Initialize
terraform init

# Validate syntax
terraform validate

# Format code
terraform fmt -recursive

# Plan (dry-run)
terraform plan -var-file="environments/dev.tfvars"

# Apply on test environment ONLY
terraform apply -var-file="environments/test.tfvars"

Testing Ansible Changes¶

cd ansible

# Syntax check
ansible-playbook playbook.yml --syntax-check

# Dry run (check mode)
ansible-playbook -i inventory/dev/hosts.ini playbook.yml --check

# Run on test VPS
ansible-playbook -i inventory/test/hosts.ini playbook.yml

# Run specific role
ansible-playbook -i inventory/test/hosts.ini playbook.yml --tags postgresql

Testing Checklist¶

Before submitting a PR, verify:

• Terraform code is formatted (terraform fmt)
• Terraform validation passes (terraform validate)
• Ansible syntax is valid (--syntax-check)
• Changes tested on non-production environment
• Documentation updated if needed
• No secrets or sensitive data in code
• Commit messages follow conventions

Documentation¶

When to Update Documentation¶

Update documentation when you:

• Add a new feature or role
• Change existing behavior
• Fix a bug that affects usage
• Improve processes or workflows

Documentation Standards¶

1. Markdown formatting:
2. Use # headers hierarchically
3. Use code blocks with language tags

4. Include examples for complex concepts

5. Structure:

6. Start with overview/purpose
7. Include prerequisites
8. Provide step-by-step instructions

9. Add troubleshooting section if relevant

10. Examples:

11. Include working code examples
12. Show both input and expected output
13. Explain non-obvious parts

Commit Messages¶

Format¶

Use conventional commit format:

<type>(<scope>): <subject>

<body>

<footer>

Types¶

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, no logic change)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Examples¶

# Good commit messages
git commit -m "feat(ansible): add monitoring role with Prometheus"
git commit -m "fix(terraform): correct PostgreSQL variable interpolation"
git commit -m "docs(readme): update installation instructions"

# Bad commit messages (avoid these)
git commit -m "fix stuff"
git commit -m "WIP"
git commit -m "changes"

Commit Message Guidelines¶

• Use present tense ("add feature" not "added feature")
• Use imperative mood ("move cursor to..." not "moves cursor to...")
• Keep subject line under 50 characters
• Separate subject from body with blank line
• Wrap body at 72 characters
• Reference issues/PRs in footer if applicable

Pull Request Process¶

1. Before Creating a PR¶

• Ensure your branch is up to date with main
• All tests pass
• Code follows style guidelines
• Documentation is updated
• Commits are clean and descriptive

2. Creating a PR¶

1. Push your branch:

git push origin feature/your-feature-name

1. Create PR on GitLab:
2. Go to the repository on GitLab
3. Click "Create merge request"

4. Fill in the template (see below)

5. PR Title Format:

[Type] Brief description (max 50 chars)

Examples:
[Feature] Add Redis caching support
[Fix] Correct PostgreSQL backup script
[Docs] Update quick start guide

3. PR Description Template¶

## Description
Brief description of what this PR does.

## Type of Change
- [ ] Bug fix (non-breaking change)
- [ ] New feature (non-breaking change)
- [ ] Breaking change (fix or feature that causes existing functionality to change)
- [ ] Documentation update

## Changes Made
- Bullet list of specific changes
- Include files/modules affected

## Testing
- [ ] Tested on dev environment
- [ ] Tested on test environment
- [ ] Terraform plan succeeded
- [ ] Ansible playbook ran successfully

## Documentation
- [ ] Updated relevant documentation
- [ ] Added inline code comments where necessary

## Related Issues
Closes #123, Related to #456

## Screenshots (if applicable)
Include screenshots for UI changes or visual documentation updates.

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] No sensitive data committed
- [ ] Documentation updated

4. PR Review Process¶

1. Automated checks: CI/CD pipeline will run
2. Code review: At least one maintainer will review
3. Feedback: Address review comments
4. Approval: Maintainer approves the PR
5. Merge: Maintainer merges the PR

5. After PR is Merged¶

• Delete your feature branch
• Update your local repository
• Close related issues if applicable

Code Review Guidelines¶

For Contributors¶

When your PR is under review:

• Be responsive to feedback
• Be open to suggestions and improvements
• Ask questions if feedback is unclear
• Be patient - reviews take time

For Reviewers¶

When reviewing PRs:

• Be constructive and respectful
• Explain why when requesting changes
• Acknowledge good work and improvements
• Test the changes if possible
• Provide specific feedback with examples

Security Issues¶

Reporting Security Vulnerabilities¶

DO NOT open public issues for security vulnerabilities.

Instead:

1. Email security concerns to: security@probatiovault.com
2. Include detailed description and steps to reproduce
3. Allow reasonable time for fix before public disclosure

Security Best Practices¶

When contributing:

• Never commit secrets, passwords, or API keys
• Use .gitignore to exclude sensitive files
• Use GitLab CI/CD variables for secrets
• Review changes before pushing
• Enable 2FA on your GitLab account

Getting Help¶

Resources¶

• Documentation: Check docs/ folder and main .md files
• Issues: Search existing issues on GitLab
• Discussions: Use GitLab discussions for questions
• Chat: [If applicable] Join our Slack/Discord channel

Asking Questions¶

When asking for help:

1. Search existing issues/docs first
2. Provide context and relevant details
3. Include error messages and logs
4. Mention what you've already tried
5. Use code blocks for code/logs

Recognition¶

Contributors will be recognized in:

• Project README.md (Contributors section)
• Release notes for significant contributions
• GitLab contributors page

License¶

By contributing, you agree that your contributions will be licensed under the same license as the project (MIT License).

Questions?¶

If you have questions about contributing, feel free to:

• Open an issue labeled question
• Reach out to maintainers
• Check existing documentation

Thank you for contributing to ProbatioVault Infrastructure! 🚀