Skip to content

Development Guide

This document provides guidelines for contributing to the Fawkes Internal Developer Platform (IDP). It includes instructions for setting up a local development environment, coding standards, and best practices for contributing to the project.

Table of Contents

Setting Up Your Development Environment

Prerequisites

Ensure you have the following tools installed:

  • Git: Version control system
  • Docker: For containerized development
  • Terraform: For infrastructure provisioning
  • kubectl: For managing Kubernetes clusters
  • Helm: For managing Kubernetes applications
  • Azure CLI (if working with Azure): Install using: 
    curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

Steps to Set Up

  1. Clone the Repository:
git clone https://github.com/paruff/fawkes.git
cd fawkes
  1. Set Up Environment Variables: Copy the .env.example file to .env and update the values:
cp .env.example .env
  1. Provision Infrastructure: Use the scripts in the infra/ directory to provision the required infrastructure:
cd infra
./scripts/ignite.sh --provider aws dev
  1. Deploy Platform Services: Navigate to the platform/ directory and deploy services:
cd platform
./deploy-services.sh
  1. Run Tests: Execute the test suite to validate your setup: 
    cd qa
./run-tests.sh

Coding Standards

Fawkes enforces comprehensive code quality standards for all languages. All code must pass automated linting before merge.

Quick Start

# Install pre-commit hooks (one-time setup)
make pre-commit-setup

# Run all linters on your changes
make lint

# Run specific linter
pre-commit run shellcheck --all-files

Language-Specific Linters

  • Bash: ShellCheck - Shell script linting
  • Python: Black (formatter) + Flake8 (linter)
  • Go: golangci-lint - Comprehensive Go linting
  • YAML: yamllint - YAML syntax and style
  • JSON: check-json - JSON validation
  • Markdown: markdownlint - Documentation linting
  • Terraform: terraform fmt, TFLint, tfsec - IaC linting and security

IDE Integration

Configure your IDE for automatic linting:

VS Code: Install recommended extensions

make setup-vscode

Other IDEs: See Code Quality Standards

Detailed Documentation

For comprehensive coding standards, linting rules, and troubleshooting:

📖 Code Quality Standards

This includes:

  • Language-specific style guides
  • Security scanning requirements
  • IDE integration guides
  • Common issues and solutions

Branching and Workflow

  1. Create a Feature Branch:
git checkout -b feature/<feature-name>
  1. Commit Changes: Write clear and concise commit messages:
git commit -m "Add <feature-name>: <short description>"
  1. Push Changes:
git push origin feature/<feature-name>
  1. Submit a Pull Request: Open a pull request (PR) on GitHub and request a review.

Testing

Fawkes includes multiple layers of testing:

  • Static Analysis: Run tools like SonarQube or Trivy to check for vulnerabilities.
  • Unit Tests: Located in the qa/unit/ directory.
  • Integration Tests: Located in the qa/integration/ directory.
  • Acceptance Tests: Located in the qa/acceptance/ directory.
  • Performance Tests: Located in the qa/performance/ directory.

Run all tests before submitting a PR:

cd qa
./run-all-tests.sh

Azure Development Best Practices

If you are working with Azure, follow these best practices:

  1. Use Azure CLI for Authentication:
az login
  1. Set the Active Subscription:
az account set --subscription <subscription-id>

  1. Follow Azure Resource Naming Conventions: Use consistent and descriptive names for resources.

  2. Use Infrastructure as Code (IaC): Use Terraform or Bicep for provisioning Azure resources.

  3. Enable Logging and Monitoring: Configure Azure Monitor and Log Analytics for all deployed resources.

  4. Secure Secrets: Store secrets in Azure Key Vault and reference them in your deployments.

Submitting Contributions

  1. Fork the Repository: Create a fork of the repository on GitHub.

  2. Make Changes: Work on your feature branch and ensure all tests pass.

  3. Submit a Pull Request: Open a PR with a detailed description of your changes.

  4. Address Feedback: Respond to reviewer comments and make necessary updates.

Need Help?

If you encounter any issues, refer to the troubleshooting guide or open an issue on GitHub.