Assetize

Learning Lab

Level 3 · 15 levels · Foundations · about 65 minutes

Level 3 — Habits of a good developer: Git, small changes and clear code

By the end: Use Git from zero: commit, branch, open a pull request, get it reviewed, merge it and settle a conflict. Make small changes you have read around first, name things well, explain the six principles you will hear every day, keep secrets out of code, and work the way this team works.

Keep this picture in your head for the whole level. Main is the team's shared line. A branch splits off for your change, commits land on it, a pull request runs the checks and gets a review, and the branch merges back. Almost everything you do with Git is one of these four moves.

A Git graph: the main line, a branch splitting off, two commits on it, a pull request with tests and a review tick, then the branch merging back into main.

Lesson 1

Git from zero: repository, commit and history

Every team that writes software keeps its code in a version control system. Ours is Git, the tool almost every software team uses. Git keeps the full history of every file: what changed, who changed it, when, and why. If a change breaks something, you can find exactly which change it was and put things back.

A repository (repo for short) is a project folder that Git looks after. Inside it sits a hidden folder called .git. That is Git's database: every saved version of every file, and the history that links them. When you clone a repository you copy that whole database to your machine. That is why nearly everything Git does, such as reading history or comparing two versions, runs on your own computer and feels instant.

A commit is one saved snapshot of the project. Git does not store a list of edits. It takes a picture of how every file looks at that moment. Files that did not change are not copied again; Git points to the copy it already has. Each commit also stores your name and email, your message, and a pointer to the commit before it, called its parent. Follow the parents back and you walk the whole history of the project.

Every commit has an ID: a 40-character checksum such as 24b9da6552252987aa493b52f8696cd6d3b00373, worked out from its contents. Change one character in one file and the ID changes, so Git always knows if anything was altered behind its back. You will usually see only the first seven characters, like 24b9da6, and that is enough to name a commit.

Branch, commit, pull request, merge. Watch the dots appear on the line: each one is a commit, a snapshot that points back to its parent. Everything later in this level builds on that line.

A Git graph: the main line, a branch splitting off, two commits on it, a pull request with tests and a review tick, then the branch merging back into main.

Where the file isIts stateHow it got there
Working tree (the files you edit)ModifiedYou changed the file and saved it in your editor
Staging area (also called the index)StagedYou ran git add: "put this version in my next commit"
The .git directory (the repository)CommittedYou ran git commit: the snapshot is stored for good

Those three states are the whole Git workflow. You change files in the working tree. You stage the changes you want in your next commit. You commit, and Git stores that snapshot permanently. The staging area is what lets you build clean commits. Say you fixed a bug and also tidied a comment in another file. Stage only the bug fix and commit it with a message about the bug. Then stage and commit the tidy-up on its own. Each commit now tells one story.

A first session with Git

git clone https://github.com/your-team/your-repo.git   # copy the repository once
cd your-repo
git status                 # what changed, and what is staged?
git diff                   # the exact lines you changed
git add src/lib/wo.ts      # stage one file
git commit -m "Show the status description on the work order card"
git log --oneline -5       # the last five commits, one line each

Remember: Write the first line of a commit message in about 50 characters, as a command: "Fix the status filter", not "Fixed stuff". Leave a blank line, then say why in a few lines if it is not obvious. You are writing for the person who reads the history in a year. That person may be you.

The mistake: Commit once on Friday with the message "updates", mixing three fixes and a rename. Do this instead: Commit each logical step as you finish it, with a message that says what changed and why. Small, clear commits are easy to review, easy to find with git log, and easy to undo.

Lesson 2

Branches, pull requests and review

A branch is a separate line of work. In Git a branch is only a movable label that points at one commit. It is so light that Git stores it as a tiny file of 41 bytes: the 40-character commit ID and a line break. When you commit on a branch, the label moves forward to your new commit. HEAD is Git's name for the branch you are on right now.

The team's shared line is main. Everyone builds on it, so it must always work. You never commit straight to main. You make a branch from main, do your work there, and ask for it to be merged back when it is ready and checked.

Branch, commit, pull request, merge. Follow one change from start to finish: the branch splits off main, two commits land on it, the pull request runs its checks and gets a review tick, then the branch merges back into main.

A Git graph: the main line, a branch splitting off, two commits on it, a pull request with tests and a review tick, then the branch merging back into main.

A normal day in Git (git switch -c is the newer form of git checkout -b)

git switch main                      # go to main
git pull                             # bring it up to date
git switch -c fix/wo-status-label    # make your branch and move onto it
# ...edit, run the tests...
git add -A
git commit -m "Work order card: show the status description"
git push -u origin fix/wo-status-label   # send the branch to GitHub

A pull request (PR) is a proposal to merge your branch into main. On GitHub it shows your change as a diff: removed lines in red, added lines in green, in the "Files changed" tab. Reviewers read it, ask questions and suggest changes on the exact lines. Automated checks, such as the tests and a build, run against it. The merge box at the bottom lists anything still in the way: a failing check, a missing approval, a conflict. A draft pull request lets you share work in progress; a draft cannot be merged until you mark it ready for review.

A pull request up close. One check has gone red, so the merge button stays grey until the cause is fixed. That is the check doing its job: a broken change never reaches main.

A pull request card: the title, a diff with red removed lines and green added lines, checks turning from running to passed, and a reviewer approving.

Review is how a team keeps quality together. It is not an exam. A good reviewer asks four questions. Does this do what the ticket asked? Is it the simplest way to do it? Are there tests? Will someone understand this in six months? When you review a colleague's pull request, comment on the code, never the person, and say what you would do instead. When your own PR gets comments, answer each one: change the code, or explain why you would keep it.

  • A title that says what changes, in everyday words.
  • What and why: two or three sentences a reviewer can read in under a minute.
  • How you tested it: the commands you ran and what they showed.
  • A screenshot for anything a user will see.
  • The part you most want a second pair of eyes on.

When the checks pass and the review is approved, the pull request is merged. Many teams, ours included, squash-merge: all the commits on the branch are folded into one tidy commit on main. Then you delete the branch and start the next piece of work from a fresh main.

The mistake: Keep one branch alive for weeks and merge main into it now and then. Do this instead: Keep branches short. Start from a fresh main and aim to merge within a day or two. The longer a branch lives, the further main moves away from it and the harder the merge becomes.

Lesson 3

Merge conflicts, calmly

Git merges most changes on its own. If you changed one file and your colleague changed another, or you both changed different parts of the same file, Git combines them without asking. A merge conflict happens when two branches changed the same lines in different ways. Git cannot know which version is right, so it stops and asks you. A conflict is not an error and nobody broke anything. It is Git being honest.

What a conflict looks like in the terminal

$ git switch fix/approve-label
$ git merge main
Auto-merging src/pages/WorkOrder.tsx
CONFLICT (content): Merge conflict in src/pages/WorkOrder.tsx
Automatic merge failed; fix conflicts and then commit the result.

$ git status
Unmerged paths:
        both modified:   src/pages/WorkOrder.tsx

What Git writes into the file

<<<<<<< HEAD
<Button>Approve work order</Button>
=======
<Button>Approve now</Button>
>>>>>>> main

Read the markers like this. Everything between <<<<<<< HEAD and ======= is the version on the branch you have checked out. Everything between ======= and >>>>>>> main is the version coming in from main. Your job is to write the final text you want, which may be one side, the other side, or a mix of both, and then delete all three marker lines.

  1. git status lists the conflicted files
  2. Open each one and search for <<<<<<<
  3. Write the final version and delete the markers
  4. Run the tests
  5. git add the file to mark it resolved
  6. git commit to finish the merge

Resolving a conflict, step by step

Branch, commit, pull request, merge. This is the moment a branch joins main. If both sides changed the same lines, this is where Git stops and hands the choice to you.

A Git graph: the main line, a branch splitting off, two commits on it, a pull request with tests and a review tick, then the branch merging back into main.

You can make conflicts rare. Pull main often, keep branches short, and keep each change small and focused. Two small changes seldom touch the same line. When a conflict does come, it is small too.

Remember: Talk before you choose. If you are not sure which version is right, ask the person who wrote the other side. Two minutes of talking beats a silent wrong guess.

The mistake: Pick "keep mine" for every conflict so the merge finishes quickly. Do this instead: Read both sides. The other change may fix something you need. Combine them where both are right, run the tests, then commit the merge.

Lesson 4

Small changes, read first, name well

A small change is easy to read, easy to test and easy to undo. A big one hides mistakes. Google's engineering practices guide puts numbers on it: about 100 changed lines is usually a reasonable size for one review, and 1,000 lines is usually too large. Spread across 50 files, even 200 lines is usually too much.

Small does not mean half done. A good small change is one self-contained step. It does one thing. It includes its tests. A reviewer can understand it without a meeting. And the product still works after it merges. A big feature becomes a short series of such steps, each one merged and working.

Small change versus big change. Two pull requests side by side. Watch how quickly the small one is reviewed and merged, and where the bug in the big one hides until it is too late.

Two pull requests side by side. The small one, twelve lines, is reviewed and merged in minutes. The big one, two thousand lines, hides a bug that slips through and breaks later.

A small changeA big change
  • Reviewed in minutes, between other work
  • Read closely, so bugs get caught
  • Easy to merge: main has barely moved
  • If the idea is wrong, little work is lost
  • Easy to roll back on its own
  • Waits days for someone with a free afternoon
  • Skimmed, because nobody can hold 2,000 lines in their head
  • Conflicts pile up while it waits
  • A wrong direction wastes days of work
  • Hard to roll back without undoing other things

Read before you write. Before you change code, read the code around it. Find who calls the function you are about to change, and what else depends on it. Search the repository for something that already does what you need. In a big codebase the most common waste is building a second copy of something that already exists. Read the tests as well: they tell you what the code is meant to do.

  1. Read the ticket twice. Write one sentence that says what "done" looks like.
  2. Search the code for the words in the ticket and find where the change belongs.
  3. Read that file and its tests. Run the tests once before you touch anything, so you know they pass.
  4. Make the smallest change that does the job. Run the tests again.
  5. Read your own diff before anyone else does. Remove debug lines and anything unrelated.

Names are the documentation people actually read. A good name says what a thing is or does, in the words the business uses. In Maximo work that means the real terms: workOrder, assetNum, siteId, availableBalance, not data2, temp or woThing. A function that returns approved work orders is called getApprovedWorkOrders, not process. If a name needs a comment to explain it, rename it.

Instead ofWriteWhy
ddaysOverdueSays what the number means
listopenWorkOrdersSays what is inside
doStuff()closeCompletedWorkOrders()Says what it does
flagisHistoryRecordA yes or no name reads as a question

The mistake: While fixing a bug, also rename a folder, reformat ten files and upgrade a library "while you are there". Do this instead: Keep the pull request to its one job. Put the tidy-up in its own small pull request, so the reviewer can see the bug fix clearly.

Remember: Stuck for more than an hour? Ask. Say what you tried and what you saw. Asking early is a strength, and it saves the team time.

Lesson 5

Six principles you will hear every day

You will hear these six names in reviews every week. Each one is a short way of saying "this will cost us later". Learn the picture for each, and you will spot them in code before a reviewer does.

Six principles. Six cards, six ideas, each with a memory hook: one source feeding many places for DRY, a gate that shuts when unsure for fail closed, a button pressed twice that still gives one result for idempotent.

Six cards, each with a picture: KISS, DRY (one source feeding many places), YAGNI, single responsibility, fail closed (a gate that shuts when unsure) and idempotent (pressing twice gives one result).

PrincipleWhat it meansIn our work
KISS: keep it simpleThe simplest design that does the job is usually best, because people can read it and fix it.One clear function that reads a work order and returns its status beats a clever framework that can read anything.
DRY: do not repeat yourselfEvery fact lives in one place, so it can never disagree with itself.Assetize keeps every tool in one registry file. The menu, the footer, the tools page and the docs all read from it, so they always match.
YAGNI: you aren't gonna need itDo not build a feature for a future that may never come.Skip the settings screen nobody asked for. Build it the week someone needs it.
Single responsibilityEach part does one job, so it has one reason to change.One page, one intent: each page on the site does one job, and everything on it serves that job.
Fail closedWhen something is missing or unsure, stop and say why, instead of guessing and carrying on.The Maximo sim refuses a field it does not know and names it in the error, instead of returning a quiet empty value.
IdempotentDoing it twice has the same effect as doing it once.A data load retried after a network drop sends each committed row only once.

YAGNI, in more depth. Martin Fowler explains it with three costs. The cost of building the feature now. The cost of delay: the useful thing you did not build while you built this one. And the cost of carrying it: every extra feature makes the code harder to change and test, for as long as it lives. He also makes a point new developers often miss. YAGNI is about features, not about code quality. Writing tests and keeping code easy to change are always worth doing.

Fail closed comes from security. A door that fails closed stays locked when the power goes. In code it means: if a required setting is missing, a value is outside its allowed list, or an answer cannot be trusted, stop with a clear message. A program that guesses and carries on will one day write the wrong value into a customer's Maximo, and nobody will notice until a report is wrong.

Fail closed in four lines of TypeScript

// Fail closed: refuse to start without the settings you need.
const host = process.env.MAXIMO_HOST;
const apiKey = process.env.MAXIMO_APIKEY;
if (!host || !apiKey) {
  throw new Error('MAXIMO_HOST and MAXIMO_APIKEY must be set. Nothing was sent.');
}
Safe to press twice. The answer gets lost on the way back, so the request goes again. On the unsafe side the retry makes a second record. On the safe side there is still exactly one.

A request is sent, the network drops the answer, and it is sent again. On the left, without protection, two records are created. On the right, with an idempotent request, there is still one record.

Idempotent, in more depth. Networks drop answers. Your code sent a request and the server did the work, but the reply never arrived. Your code cannot tell, so it tries again. In HTTP, GET, PUT and DELETE are idempotent by design: sending one twice leaves the server as it would be after one. POST and PATCH are not guaranteed to be. Two POSTs that create a work order create two work orders. So before you retry a create, make it safe: look the record up by a reference you chose, and create it only if it is not there yet.

The mistake: Copy the same 20-line date formatting block into four files because it is quicker today. Do this instead: Put it in one well-named function and call it from all four places. When the rule changes, you change it once (DRY).

Lesson 6

Secrets and environment variables

A secret is anything that lets someone in: an API key, a password, a token, a private certificate. A Maximo API key is a secret. Whoever holds it can do everything the Maximo user behind it can do, from anywhere, with no password and no screen.

Where secrets live. Follow the key typed into the code: committed, pushed, then copied to every laptop and every fork that clones the repository. It is now in many places at once.

An API key typed into code is committed, pushed and copied to clones, build logs and forks. Deleting it in a new commit leaves it in the old one, so the key is rotated. On the safe side the code holds only the name, the value sits in a secret store, only the running program reads it and logs mask it.

Git makes leaks worse, because Git keeps history by design. Delete the key in your next commit and it is still in the earlier one. Every clone already has a copy. GitHub's own guidance is clear about the order of work: if a secret was committed, the first step is to revoke or rotate it, so the leaked value stops working. Rewriting history afterwards cannot reach other people's clones or forks.

Where secrets live instead: in environment variables or a secrets store. An environment variable is a named value that the operating system hands to a running program, such as MAXIMO_APIKEY. The code knows only the name. The value is set on the machine or in the deployment, never in the repository. The Twelve-Factor App guide gives a simple test: could you make your code public right now without leaking a single credential? If the answer is yes, your secrets are in the right place.

The value lives outside the code

# In your terminal, or a .env file that Git ignores. Never in code:
export MAXIMO_APIKEY="paste-your-key-here"

# The code and the command only know the name:
curl -H "apikey: $MAXIMO_APIKEY" "https://your-maximo.example.com/maximo/api/os/mxapiasset?lean=1&oslc.pageSize=1"
Where secrets live. The same key, now kept in an environment variable store. Only the running program reads it. The repository holds the name, never the value.

An API key typed into code is committed, pushed and copied to clones, build logs and forks. Deleting it in a new commit leaves it in the old one, so the key is rotated. On the safe side the code holds only the name, the value sits in a secret store, only the running program reads it and logs mask it.

Our own products follow the same rule. Workbench 3 keeps your Maximo API key in the workspace credential store, never in a package. The environment files that move a connection between the Data Workbench, Workbench 3 and the Studio never carry the key.

  • Never put a secret in code, a commit, a pull request, a ticket, a chat message or a screenshot.
  • Never print a secret in a log. Log the request without its apikey header.
  • Keep .env files out of Git: add them to .gitignore before you create them.
  • Send API keys in a header, not in the address. Addresses end up in server logs and browser history.
  • Give each program its own key, tied to a Maximo user with only the access that program needs.

Remember: If you ever expose a secret, say so straight away. The key must be replaced; deleting the message or the commit is not enough. Reporting it fast is exactly what the team wants from you.

Lesson 7

How this team works

Every team has its own way of working. Here is ours. It is short on purpose, and every line of it exists because the opposite once cost someone a day.

HabitWhat it means here
Start from current mainFetch main and branch from it before you change code. Never revive an old branch wholesale; rebuild the pieces you still need on a fresh one.
pnpm, alwaysWe install and run everything with pnpm. Never npm or yarn, and never commit their lock files.
Keep pull requests focusedOne job per pull request. Take unrelated file changes out before review.
Run the checks that fit the changeA wording change needs a content check. A logic change needs its unit tests, the type check and a build.
Any failure you find, you fixIf a test, build or check fails in front of you, it is yours to fix in the same task, even if your change did not cause it.
Secrets stay outNo keys, tokens, passwords or customer data in source, logs or screenshots.
Merge when greenWhen the checks pass and nothing is waiting on review, the pull request is squash-merged into main.

Our checks run on your machine before you push: the tests, the type check and the build. They are the gate. So you run them, you read what they print, and you only say a check passed when you saw it pass. "It should be fine" is not a test result.

The checks you will run most

pnpm install                                      # once, after you clone
pnpm --filter @workspace/assetize test:lib        # the library tests
pnpm --filter @workspace/assetize run typecheck   # the TypeScript type check

# The test that checks this very lab, one level at a time:
cd artifacts/assetize
LAB_LEVEL=coding-habits LAB_PICTURES=partial node --experimental-strip-types --test src/lib/learning-lab.test.ts
A pipeline with gates. A unit test turns red and the change stops before it reaches DEV. That stop protects everyone downstream. Your job is to find out why it turned red.

A change flows through build, unit tests, deploy to DEV, integration and UI tests, approval, deploy to TEST then PROD and a smoke test. Each stage turns green in turn.

"Any failure you find, you fix" surprises new people. In many places, a failing test your change did not cause is somebody else's problem. Here it is yours. You found it and you have the context, so you reproduce it, fix the cause, run the check again and say in your pull request what you fixed. If the fix needs someone's approval, such as a change to a protected page, you say exactly what fails, why, and the fix you would make.

The mistake: A test fails, so you delete it, skip it, or edit it until it passes. Do this instead: A failing test is information. Find out why it fails. Fix the code, or fix the test only when the test itself is wrong, and say which one you did in the pull request.

Remember: Say what you ran. "Ran test:lib and typecheck, both pass" in a pull request is worth more than any amount of "should work".

Check yourself: the Level 3 quiz

18 questions. Pass mark 70%.

  1. Look at the picture. What has just happened? (picture: Branch, commit, pull request, merge)
    • A new branch has split off main, so the work stays off main until it is checked
    • Main has been deleted
    • A pull request has been merged
    • Two commits have been undone
  2. What does a Git commit store?
    • Only the lines you changed
    • A snapshot of the project, your name and email, your message and a pointer to its parent commit
    • A copy of the whole database
    • A screenshot of your editor
  3. You edited a file and ran git add on it, but have not committed yet. What state is the file in?
    • Modified
    • Staged
    • Committed
    • Merged
  4. Which pull request can be merged?
    • Pull request A
    • Pull request B
  5. Look at the picture. Before this step happens, what should be true? (picture: Branch, commit, pull request, merge)
    • The checks have passed and a reviewer has approved
    • The branch is at least a month old
    • Every file in the repository changed
    • Nobody has read the code
  6. A merge stops with a conflict. In the file you see <<<<<<< HEAD, then some lines, then =======. What are those first lines?
    • The version from the branch you have checked out
    • The version coming in from main
    • A comment Git added for you
    • Lines Git deleted
  7. You have edited a conflicted file into its final form. Which command marks it resolved?
    • git add
    • git push --force
    • git reset
    • git clone
  8. Look at the two pull requests. Which one is more likely to let a bug through? (picture: Small change versus big change)
    • The small one, because it is reviewed too quickly
    • The big one, because nobody can read 2,000 lines closely
    • Both equally
    • Neither, tests catch everything
  9. Google's engineering practices give a rule of thumb for one change. Which is it?
    • About 100 lines is usually reasonable; 1,000 is usually too large
    • Never more than 10 lines
    • At least 1,000 lines, so reviews are worth the time
    • Size does not matter
  10. Assetize keeps every tool in one registry file, and the menu, footer and tools page all read from it. Which principle is that?
    • YAGNI
    • DRY
    • Fail closed
    • Idempotent
  11. Which picture shows an idempotent request?
    • Picture A
    • Picture B
  12. Which HTTP method is not guaranteed to be idempotent?
    • GET
    • PUT
    • DELETE
    • POST
  13. A required setting is missing when your program starts. What does a program that fails closed do?
    • Carries on with an empty value
    • Guesses a sensible default and tells nobody
    • Stops with a message that names the missing setting
    • Retries for ever
  14. Which picture keeps the API key safe?
    • Picture A
    • Picture B
  15. You pushed a commit that contains an API key. What is the first thing to do?
    • Delete the line in the next commit and say nothing
    • Revoke or rotate the key, and tell the team
    • Rename the file
    • Make the repository private and carry on
  16. Someone suggests adding a settings screen "in case a customer wants it one day". Which principle says wait?
    • DRY
    • YAGNI
    • Idempotent
    • Single responsibility
  17. Look at the picture. A unit test fails on your branch, and your change did not touch that code. What do you do here? (picture: A pipeline with gates)
    • Merge anyway, it is not your test
    • Delete the test
    • Reproduce it, fix the cause, run the check again and say what you fixed
    • Wait for someone else to notice
  18. Which package manager does this team use?
    • npm
    • yarn
    • pnpm
    • Whichever is installed

Remember it as a picture

  • Commit: A snapshot of the project with your name, your message and a pointer to its parent. Its ID is a 40-character checksum.
  • Branch: A movable label pointing at a commit: a 41-byte file. Work on a branch, never straight on main.
  • Pull request: A proposal to merge your branch into main: the diff, the checks and the review, in one place.
  • A red check: Keeps the merge button grey until the cause is fixed. Read it; never delete the test to make it pass.
  • Merge conflict: Two branches changed the same lines. Write the final version, delete the markers, git add, git commit.
  • Small changes: About 100 lines is usually a good review; 1,000 is usually too many. One self-contained step at a time.
  • KISS: Keep it simple: the simplest design that does the job is the one people can read and fix.
  • DRY: Do not repeat yourself: one source for each fact, read by every place that needs it.
  • YAGNI: You aren't gonna need it: build features when they are needed. It never excuses skipping tests or tidy code.
  • Single responsibility: Each part does one job and has one reason to change. On our site: one page, one intent.
  • Fail closed: When unsure, stop and say why. Never guess and carry on.
  • Idempotent: Twice has the same effect as once. Make creates safe to retry by looking the record up first.
  • A committed secret: Git keeps it in history and every clone. Revoke or rotate the key first, then clean up.
  • Environment variable: A named value the running program reads, such as MAXIMO_APIKEY. The code holds the name, never the value.

Where these facts come from

Try it on the real tools

How did Level 3 go?

Rate the level and say what worked, what did not, what you liked and what you did not. Send it now, or with your full report.