Build and ship projects

Turning skills into finished, shareable work: scoping, JSON and APIs, dependencies, configuration, a good README and publishing on GitHub.

Scoping a small project

Also called MVP, minimum viable product, milestones

What: Cutting an idea down to the smallest version that solves one real problem end to end, then splitting it into a handful of milestones.
Why: Finished small projects teach more and show more than ambitious unfinished ones.
Example: Not "a personal finance app", but "a command-line tool that reads my bank CSV and prints spending per category per month". Milestones: parse the CSV, categorise, total, print, test, README.

Watch out

Starting with login, a database and a UI before the core logic works at all.

Reading and writing JSON

Also called JSON, serialisation, parsing JSON, JSON.parse

What: JSON is a text format for objects, arrays, strings, numbers, booleans and null. Serialising turns your data into JSON; parsing turns JSON back into data.
Why: It is how most APIs and many config and save files exchange data. Python, JavaScript and C# ship a JSON library; Java and C++ usually add Jackson or nlohmann/json.

Python

import json
from pathlib import Path

path = Path("ledger.json")
data = json.loads(path.read_text(encoding="utf-8"))
data["entries"].append({"amount": 12.5, "note": "lunch"})
path.write_text(json.dumps(data, indent=2), encoding="utf-8")

Watch out

Trusting parsed JSON blindly: fields can be missing, null or the wrong type, so validate before use.

Calling a public API

Also called HTTP, REST API, fetch, HttpClient, requests

What: Sending an HTTP request (usually GET or POST) to a web service and reading its response, typically a status code plus a JSON body.
Why: Public APIs give a small project real data (weather, books, transport) without building a backend.

Python

import requests

resp = requests.get(
    "https://jsonplaceholder.typicode.com/todos/1",
    timeout=10,
)
resp.raise_for_status()
todo = resp.json()
print(todo["title"])

Watch out

Assuming the call succeeds: set a timeout, check the status code and handle the network being down.

Virtual environments and pip

Also called venv, pip, requirements.txt, uv, pyproject.toml

What: A virtual environment is a project-local folder with its own Python packages. pip installs packages from PyPI into it, and a requirements file or pyproject.toml records them.
Why: Each project gets the versions it needs without breaking others, and anyone can recreate the setup. uv is a popular faster tool that does the same job.

Shell

python -m venv .venv
source .venv/bin/activate
python -m pip install requests pytest
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt

Watch out

Installing packages globally with sudo pip, or forgetting to activate the environment, so the code runs on your machine only.

Configuration and secrets

Also called environment variables, .env, API keys

What: Settings that change between machines (API keys, URLs, file paths) are read from environment variables or a local config file instead of being written into the code.
Why: It keeps secrets out of Git and lets the same code run on your laptop, a friend's machine and a server.

Python

import os

api_key = os.environ["WEATHER_API_KEY"]
debug = os.getenv("DEBUG", "false") == "true"

Watch out

Committing an API key: bots scan GitHub within minutes, so revoke the key at once, since deleting the commit is not enough.

Writing a README

Also called README.md, project documentation

What: The front page of a repository: what the project does and for whom, a demo, how to install, run and test it, how it works and its known limits.
Why: It is the first thing a reviewer, teammate or employer reads, and often the only thing. A project nobody can run might as well not exist.

MARKDOWN

# Ledger
One sentence: what it does and who it is for.

## Demo
A GIF or two screenshots.

## Getting started
Requirements, then install and run commands.

## Running tests
## How it works
## Limitations and next steps

Watch out

Leaving the default template, or skipping the exact commands to run the project from a fresh clone.

Publishing on GitHub

Also called gh repo create, licence, portfolio

What: Pushing a project to a public GitHub repository with a README, a licence, a .gitignore and a clean history of meaningful commits.
Why: It backs your work up, makes it easy to share, and shows how you work, not just what you built.

Shell

git remote add origin https://github.com/you/ledger.git
git branch -M main
git push -u origin main

gh repo create ledger --public --source=. --push

Watch out

Pushing one "initial commit" containing the entire finished project, which hides how it was built.

Go deeper