Skip to content

development.md

Latest commit

 

History

History
360 lines (261 loc) · 8.04 KB

development.md

File metadata and controls

360 lines (261 loc) · 8.04 KB

Development Guide

Contributing to the Fedora Desktop Configuration Manager.

Welcome Contributors!

This guide helps you:

  • Set up your development environment
  • Understand the branching strategy
  • Follow Ansible style guidelines
  • Test your changes
  • Submit pull requests

Essential reading for:

  • First-time contributors
  • Anyone adding new playbooks
  • Maintainers creating version branches

Quick links:

Development Environment

Recommended Setup

Project Setup

# Clone repository
git clone https://github.com/LongTermSupport/fedora-desktop.git
cd fedora-desktop

# Install development dependencies
sudo dnf install -y ansible ansible-lint

# Install Ansible Galaxy requirements
ansible-galaxy install -r requirements.yml

# Set up git security hooks (deployed automatically by play-git-hooks-security.yml)
git config core.hooksPath scripts/git-hooks

Branching Strategy

Branch Naming

  • Format: F<VERSION> (e.g., F42, F43)
  • Each branch targets specific Fedora version
  • Version defined in vars/fedora-version.yml

Creating New Version Branch

When Fedora releases a new version:

# 1. Update version in configuration
vim vars/fedora-version.yml
# Change: fedora_version: 44

# 2. Commit the change
git add vars/fedora-version.yml
git commit -m "Update target Fedora version to 44"

# 3. Create and push new branch
git checkout -b F44
git push -u origin F44

# 4. Set as default branch on GitHub
gh repo edit --default-branch F44

# 5. Update branch-specific changes
# - Test all playbooks
# - Update package versions if needed
# - Fix any compatibility issues

After Changing the Default Branch — Resync Local Clones

Step 4 above changes the default branch on GitHub, but existing clones keep pointing their local origin/HEAD at the old default (e.g. main or the previous F<VERSION>). This is a stale local symref, not a GitHub state — so git rev-parse origin/HEAD, git-oss-checkout-default, and similar helpers will resolve to the wrong branch until each clone is resynced.

Every contributor (and any automation) should run, once, after the default branch moves:

git remote set-head origin --auto   # repoints local origin/HEAD to the new default

Verify with:

git symbolic-ref refs/remotes/origin/HEAD          # -> refs/remotes/origin/F44
gh repo view --json defaultBranchRef --jq .defaultBranchRef.name   # -> F44

The two must agree. If they disagree, the local symref is stale — re-run the set-head command above.

Branch Lifecycle

  • Active: Current Fedora version branch
  • Maintenance: Previous version (critical fixes only)
  • Archive: Older versions (reference only)

Ansible Style Guide

Playbook Structure

- hosts: desktop
  name: Descriptive Name  # Clear, action-oriented
  become: true  # Only if needed
  vars:
    root_dir: "{{ inventory_dir }}/../../"
  vars_files:
    - "{{ root_dir }}/vars/fedora-version.yml"  # If version-dependent
  tasks:
    - name: Clear task description
      module_name:
        parameter: value

File Modifications

Always use blockinfile over lineinfile:

- name: Update configuration
  blockinfile:
    path: /path/to/file
    marker: "# {mark} ANSIBLE MANAGED: Purpose"
    block: |
      configuration content
    create: yes  # If file should be created
    owner: "{{ user_login }}"
    group: "{{ user_login }}"
    mode: '0644'

Package Management

# Simple installations
- name: Install packages
  package:
    name: "{{ packages }}"
    state: present
  vars:
    packages:
      - package1
      - package2

# Fedora-specific features
- name: Install from DNF
  dnf:
    name: package-name
    state: present
    enablerepo: repo-name  # If needed

Variable Naming

  • Use descriptive names: user_login, not ul
  • Group related variables: lastpass_accounts, github_accounts
  • Document complex variables with comments

Task Organization

  • Group related tasks with block
  • Use meaningful tags for selective execution
  • Order tasks logically: checks → installation → configuration

Testing

Local Testing

# Syntax check
ansible-playbook playbooks/playbook-main.yml --syntax-check

# Dry run
ansible-playbook playbooks/playbook-main.yml --check

# Run specific tags
ansible-playbook playbooks/playbook-main.yml --tags packages

# Test individual playbook
ansible-playbook playbooks/imports/play-basic-configs.yml -vv

Debugging

# Verbose output levels
-v    # Basic debug
-vv   # More detailed
-vvv  # Connection debug
-vvvv # Full debug

# Step through execution
ansible-playbook playbook.yml --step

# Start at specific task
ansible-playbook playbook.yml --start-at-task="Task Name"

Fact Gathering

# View all facts
ansible desktop -m setup

# Filter facts
ansible desktop -m setup -a "filter=ansible_distribution*"

# Save facts to file
ansible desktop -m setup --tree /tmp/facts

Run QA Before Committing

Required before every commit that touches Bash, Python, or Ansible files:

./scripts/qa-all.bash

For GNOME Shell extension JavaScript, run ESLint directly:

cd /workspace/extensions && node_modules/.bin/eslint speech-to-text@fedora-desktop/extension.js

For changes to files/var/local/claude-yolo/ccy-ctrl-z-patch.js, run the dedicated patch QA:

./scripts/qa-ctrl-z-patch.bash

See CLAUDE/QA.md for full details on what each check covers.

Contributing

Before Submitting

  1. Test on fresh Fedora installation
  2. Verify idempotency (run twice, no changes second time)
  3. Check style compliance with ansible-lint
  4. Update documentation if adding features
  5. Test both with and without third-party repos

Pull Request Process

  1. Fork repository
  2. Create feature branch from appropriate version branch
  3. Make changes following style guide
  4. Test thoroughly
  5. Submit PR with clear description

Adding New Playbooks

  1. Create in appropriate directory:

    • imports/ for core features
    • imports/optional/common/ for general optional features
    • imports/optional/hardware-specific/ for hardware support
    • imports/optional/experimental/ for bleeding-edge

  2. Follow naming convention: play-<feature-name>.yml

  3. Include standard headers:

- hosts: desktop
  name: Feature Description
  become: true  # If needed
  vars:
    root_dir: "{{ inventory_dir }}/../../"
  1. Document in docs/playbooks.md

Commit Messages

Use conventional format:

type: description

- Detail 1
- Detail 2

Fixes #issue

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • style: Formatting
  • refactor: Code restructuring
  • test: Testing
  • chore: Maintenance

Security Considerations

Vault Usage

# Encrypt sensitive variables
ansible-vault encrypt_string 'secret' --name 'var_name'

# Always use vault for:
# - API keys
# - Passwords
# - Tokens
# - Private configuration

File Permissions

- name: Secure file
  copy:
    src: source
    dest: /path/to/dest
    owner: "{{ user_login }}"
    group: "{{ user_login }}"
    mode: '0600'  # Restrictive for sensitive files

Never Commit

  • vault-pass.secret
  • Personal API keys
  • SSH private keys
  • Temporary files in untracked/

Resources