Skip to content

00. Headstart Guide

Overview

This guide is something I created to help you start Python projects quickly and with confidence. I know that setting up a project in a dynamic environment can involve many moving parts, and it"s easy to miss important configurations. That"s why I"ve gathered the essential practices, tools, and lessons learned into one place. Treat this handbook as a reference you can rely on whenever you begin or contribute to a project, so your setup and workflow stay smooth and consistent.

Know the System Before You Start

Before touching any code, make sure you understand the project. I take the time to see the full picture and don"t start coding until I can confidently explain how every part of the system fits together.

Document Target / Purpose
Project README Understand what the project is, why it exists, and what it aims to deliver.
Architecture docs (SAD) See system flows, diagrams, and how all components fit together.
Cloud provider docs reference Review only the cloud services the project depends on.
Data/storage documentation included for the project Understand how the project stores, reads, and manages data.
Service account usage guide Know which identities are used and what permissions they have.
Implementation notes Get the high-level logic of how the system is intended to work overall.
CI/CD flows Understand how the project builds, tests, and deploys.

For a deeper dive, I also recommend reading the following:

Toolchains

Prerequisites

To keep development consistent, ensure the following tools are installed and properly configured:

  • Code Editor. I used Visual Studio Code

  • Docker

  • Docker compose

  • git

  • Python version 3.9.x+ (or 3.12.x+ is recommended)

  • Python package manager: uv

  • Database clients

  • GitHub CLI/GiLab CLI. Depend on the platform

  • Cloud SDK (For Google Cloud Platform: gcloud, for AWS: awscli)

  • (Optional - Infrastructure) Terraform, Ansible

  • File format handling: jq, yq

  • pre-commit

  • make to run Makefile targets

Permissions

Before that, make sure you have permissions to access the project's resources.

  • GitHub (2FA) with user account

  • Google Cloud Platform (GCP) with Service Account

Environment Setup

[1] Set up your Python virtual environment and install dependencies:

export REPOSITORY_REMOTE_ORIGIN_URL=<repo_url>
git clone $REPOSITORY_REMOTE_ORIGIN_URL [local-repo]
cd [local-repo]
python3 -m venv venv
source venv/bin/activate
pre-commit install
uv pip install -r requirements-dev.txt -r requirements.txt

[2] Set Up the PATH Variable

Some tools installed on your system need to be accessible from the command line. To do this, add their location to the PATH environment variable.

Run the following command in your terminal:

export PATH="$PATH:$HOME/.local/bin"

Shell Configuration

[1] Establish your shell profiles with environment variables

export PROJECT_ID=
export PROJECT_REGION=

echo "PROJECT_ID=$PROJECT_ID" >> ~/.bashrc
echo "PROJECT_REGION=$PROJECT_REGION" >> ~/.bashrc
echo "LOCATION=$PROJECT_REGION" >> ~/.bashrc

To effective load, reload your shell:

source ~/.bashrc

Developer Workflow

The steps below define the expected development process for all contributions.

  1. Sync with the default branch (e.g. master, develop).

  2. Create a branch for features, fixes, enhancements, or documentation.

  3. Configure environment variables using .env or .ini files from example.*.{env,ini}.

  4. Develop solutions to meet specified requirements and target outcomes.

  5. Write and run unit and integration tests locally until all pass.

  6. Enforce coding standards using ruff and pre-commit, following the Google Python Style Guide.

  7. Open a pull request with a clear description of the changes.

  8. Address reviewer feedback and resolve issues.

  9. Merge into the target branch (e.g. master, production).

  10. (Optional) Clean up temporary files or cached resources.

Development Best Practices

These practices ensure your work integrates cleanly with the team"s workflow.

Code Quality

  • Follow the Google Python Style Guide

  • Add type hints whenever possible

  • Format code with black and isort

  • Use pytest for tests; aim for meaningful coverage, not 100% for the sake of numbers

  • Use pre-commit to run Makefile targets before committing

  • Use ruff to check for coding standard violations

  • Use uv as package manager for Python packages

  • Using Makefile to run automated, reusable tasks

Supoorted toolchains for IDE

Based on the use of IDE from Visual Studio Code, the following is recommended:

  • Theme: through Material Icon Theme

  • autoDocsString: give the template for docstring in Python

Enhance security through 2FA

This is an important step for security:

  • For all members, applied for personal email with 2FA turn on

  • For all members, applied for GCP service account with 2FA turn on