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.

Java

record Entry(double amount, String note) {}
record Ledger(List<Entry> entries) {}

var mapper = new ObjectMapper();
var file = new File("ledger.json");
Ledger ledger = mapper.readValue(file, Ledger.class);
var entries = new ArrayList<>(ledger.entries());
entries.add(new Entry(12.5, "lunch"));
mapper.writerWithDefaultPrettyPrinter()
    .writeValue(file, new Ledger(entries));

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.

Java

var url = "https://jsonplaceholder.typicode.com/todos/1";
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder(URI.create(url))
    .timeout(Duration.ofSeconds(10))
    .build();
HttpResponse<String> res =
    client.send(request, HttpResponse.BodyHandlers.ofString());
if (res.statusCode() != 200) {
  throw new IOException("HTTP " + res.statusCode());
}
System.out.println(res.body());

Watch out

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

Maven and Gradle

Also called Maven, Gradle, pom.xml, build.gradle.kts, Maven Central, build tool

What: Build tools that download dependencies from Maven Central, compile, run tests and package a JAR. Maven uses a pom.xml file; Gradle uses build.gradle.kts.
Why: Nobody manages Java libraries by hand. A build file means anyone can clone the project and run one command to build and test it.

Shell

mvn test
mvn package
java -jar target/ledger-1.0.jar

./gradlew test
./gradlew build

Watch out

Running a system-installed Gradle instead of the project wrapper ./gradlew, so the build uses a different version.

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.

Java

String apiKey = System.getenv("WEATHER_API_KEY");
if (apiKey == null) {
  throw new IllegalStateException("WEATHER_API_KEY not set");
}

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