Lesson 0008 · delivery

Packaging & The README

Two of the five evaluation criteria are decided after the code is finished. Most candidates spend ten minutes here.

Look at the marking scheme again:

Code readability and organisation
Proper use of object-oriented programming principles
Handling edge cases and exceptions
Implementation of bonus features
Clarity and thoroughness of the README file

One fifth of the stated criteria is a document. And every one of the other four is read through whatever you send — if the assessor cannot build it, the best code in the pile scores nothing.

Part one · how to send it

The brief is explicit, and it is an instruction rather than a suggestion:

Create a zip file (.7z or .zip) containing the code and any other files for your project. … Email the zip file to your talent acquisition contact as an attachment when completed.

The answer: a zip with the `.git` directory inside it

The recommendation

Send the zip they asked for, and put your .git folder inside it. You comply exactly with the instruction, and the assessor who wants the commit narrative gets it by running git log in the folder they just unzipped. The one who does not care never notices.

Then also push to GitHub and put the link at the top of the README — as a convenience, never as a replacement.

Option	Verdict
Zip including `.git`	Do this. Follows the instruction literally, carries the full history, needs no account and no network from the reader. Measured at 76 KB for the finished project — it will pass any mail filter.
GitHub link as well	Yes, in addition. Nicer to browse, and shows you are comfortable working in the open. Make it public — a private repo needing an invitation is friction on their side.
GitHub link instead	No. It ignores a direct instruction, and the recipient is a talent-acquisition contact who may forward an attachment far more happily than a link.
Zip without `.git`	Wasteful. You did the work of writing thirteen careful commit messages. Do not throw the artifact away at the last step.
`git archive` / `git bundle`	No. `git archive` deliberately excludes `.git`, so it defeats the purpose. A `.bundle` requires the reader to know how to clone from one.

The exact commands, verified end to end

Task · the packaging recipe

# 1. Clean, so no build output goes in the zip.
cd ~/Desktop/java-guild-candidate-test-intermediate-main
export JAVA_HOME=$(/usr/libexec/java_home -v 25)
~/.local/maven/bin/mvn clean

# 2. Confirm nothing is uncommitted. This must print nothing.
git status --short

# 3. Zip the lot, excluding build output and IDE files, INCLUDING .git
cd ..
zip -qr tom-spencer-library-management-system.zip \
    java-guild-candidate-test-intermediate-main \
    -x '*/target/*' -x '*/.idea/*' -x '*.DS_Store'

Then verify it the way the assessor will experience it — this step is not optional:

mkdir /tmp/assessor && cd /tmp/assessor
unzip -q ~/Desktop/tom-spencer-library-management-system.zip
cd java-guild-candidate-test-intermediate-main
git log --oneline          # the history survived?
git status --short         # clean tree?
mvn clean test             # builds from cold?

Run against the reference solution, that verification produced:

$ git log --oneline
617d47d Document how to build and run the system
7bedfc3 Add starter project as supplied

$ git status --short
(nothing - clean)

$ mvn clean test
[INFO] Tests run: 15, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

Two things that go wrong at this step

Some corporate mail filters strip or quarantine .zip attachments. If it bounces, the brief also permits .7z. Failing that, send a link to the GitHub repo and say in the email that the zip was blocked, so it reads as a mail-server problem rather than as you ignoring the instruction.

Do not zip a directory containing target/. Compiled .class files are the single most common reason an attachment gets quarantined, and they bloat the archive enormously. That is what mvn clean in step 1 is for.

Part two · the README they actually mark

The brief asks the README to contain three things. Give it six.

Section	What goes in it
How to build and run	Exact commands, copy-pasteable, including the Java version. Assume nothing.
The approach	The reframe from Lesson 0001: this was read as a legacy-code exercise. Golden master first, then unit tests, then test-driven fixes. Two sentences on why the unused `exceptions` package told you where to start.
What was wrong, and what changed	A short table of the defects with the fix. This is the section that proves you found things.
Design decisions	Checked exceptions; the `LibraryException` supertype; `Optional` over `null`; the repository interface; the enum; why no Mockito. One or two lines each, each naming the trade-off.
Deviations from the brief	`borrowBook` returns `void`; `searchBook` returns `Optional`. With reasons. This section is the highest-value paragraph in the document.
What I did not build, and why	SQLite persistence; multiple copies of a title; concurrency. Scope discipline, stated deliberately rather than looking like omissions.

The two sections that separate you from the pile

Almost every candidate will write “how to run” and “what I built”. Very few will write Deviations from the brief and What I did not build, and why.

Those two sections do something no amount of code can: they show you can tell the difference between a requirement, a judgement call, and scope creep — and that you will flag a disagreement rather than quietly act on it. That is the single most useful thing a consultancy wants to know about a new hire, which is precisely what Solirius is.

Build instructions: be more specific than feels necessary

## Requirements
Java 11 or later. The project targets Java 11 (`maven.compiler.release`),
and has been built and tested on Temurin 25.

## Build and test
    mvn clean test

## Run
    mvn clean compile
    java -cp target/classes com.solirius.intermediate.library.Main

The library state is written to `libraryState.txt` in the working
directory on exit, and reloaded on the next start. A different path
may be given as the first argument.

Test your own instructions

Follow your README literally, in a fresh terminal, from the unzipped copy in /tmp. Not from memory — literally, copying and pasting each block. Instructions that do not work are worse than no instructions, and this is the criterion they told you they would mark.

Drill

Why include the .git directory in the zip rather than sending only a GitHub link?

Because git history cannot be pushed to a remote host without losing data
Because the brief asked for a zip, and this satisfies it without losing work
Because a zipped repository is smaller than the equivalent GitHub checkout
Because assessors are generally not permitted to visit external code hosts

Pushing loses nothing. GitHub would show the history perfectly well.

This is it, and it is a “why not both” answer. The instruction says zip; the history is valuable; putting .git in the zip satisfies the instruction and keeps the value. Add the GitHub link too, as a courtesy rather than a substitute.

Size is not the argument — the whole thing is 76 KB either way. And an argument from convenience would not override an explicit instruction.

Some organisations do restrict this, which is a further small reason to attach rather than link — but you cannot assume it, and it is not the primary reason.

Which README section is most likely to distinguish your submission?

A detailed description of each class and the methods that it now contains
A list of the Java and Maven versions the project was developed against
A diagram showing how the classes in the project relate to one another
An account of where you departed from the brief, and why you did so

This duplicates the javadoc and goes stale immediately. A reviewer would rather read the code, which is authoritative.

Necessary, and it belongs there — but every competent candidate includes it, so it cannot distinguish you.

Nice for a large system. For six classes it is decoration, and time spent drawing it is time not spent on the sections that carry judgement.

This is the differentiator. It is the only section that reveals whether you can distinguish a requirement from a judgement call, and whether you surface disagreements rather than acting on them silently. For a consultancy placing engineers onto client teams, that is close to the whole question.

Before zipping, why run mvn clean and check git status?

Build output bloats the archive and is a common cause of mail quarantine
Maven refuses to package a project whose working tree has been modified
Compiled classes from a newer JDK would prevent the assessor recompiling
Git will not include ignored files in an archive unless the tree is clean

Both reasons, and both are real. .class files inside an emailed archive are a classic trigger for corporate attachment filtering, and target/ is far larger than the source. The git status check catches the other disaster: shipping a zip whose working tree contains work you never committed, so the history and the code disagree.

Maven has no such rule and knows nothing about git.

Stale classes would simply be overwritten by a rebuild. Annoying, not blocking.

You are using zip, not git archive, so git’s ignore rules are not applied at all — which is exactly why you pass -x patterns by hand.

The email

Three sentences. Do not sell; the work does that.

Hi [name],

Attached is my submission for the Java Guild candidate test - a Library
Management System built to the Intermediate tier (Graduate + Intermediate
requirements).

The zip includes the full git history, so the commit log walks through the
approach in order. The README covers how to build and run it, the design
decisions, and the two places I deviated from the brief. It's also at
github.com/TomSpencerLondon/... if that's easier to browse.

Best,
Tom

Final checklist

Work through the submission checklist before you send. It exists so that the last five minutes cannot undo the previous fifteen hours.

Read this

Primary source

The Instructions for Submission and Evaluation Criteria sections of the brief. Re-read both the evening you submit, with your finished README open beside them, and check off each criterion against something concrete in your submission. If you cannot point at the thing that answers a criterion, it is not answered.

Carry on

Reference card: Submission checklist
Next: Lesson 0009 — The Interview Viva — defending every decision out loud

Show me your README draft before you send it. It is the one part of the submission where a second reader is worth most, because you cannot see your own assumed knowledge.