Skip to content

episode 003

Jump to bottom
OGAWA Keiji edited this page Sep 3, 2026 · 7 revisions

Setting Up the Development Environment

This is the first episode in which I actually start developing okoze.

In the previous episode, I decided on the development environment.

Now I will set it up and make sure that it works.

More importantly, I will start applying the development process described in the first episode.

What I Will Implement

The first feature is deliberately small:

🟧 1A Development environment

1A is the feature ID.

Before starting the implementation, I write down the tests that will tell me whether the feature is complete.

🔴 The project can be edited in VSCode
🔴 The Web Server can be started and the Canvas and a shape can be displayed in the browser
🔴 The project contents can be viewed in the GitHub repository

These tests are intentionally simple.

I am not trying to build a complete development environment. I only need enough to start developing the application.

My Development Environment

The development environment is the one I described in the previous episode.

Purpose Tool
Development machine Mac mini M4
IDE Visual Studio Code
Browser Chromium
Development server Live Server
Programming language JavaScript
Graphics Canvas API
Version control Git / GitHub

The exact versions are not particularly important at this stage.

For reference, my current environment is:

  • macOS: Tahoe 26.5.2
  • Visual Studio Code: 1.133.0
  • Chromium: 151.0.7922.137
  • Git: 2.50.1

I also use some Visual Studio Code extensions, but these are not requirements for the project. Readers can use whatever extensions they prefer.

The same applies to the operating system, IDE, and browser.

Creating the Repository

First, I create an empty repository on GitHub.

I then clone the repository to my development machine.

At this point, the repository contains no application code yet.

That's all I need to do here.

Creating the First Page

I open the cloned project in Visual Studio Code.

I create three files:

index.html
main.js
style.css

There is no framework or build system.

The first index.html contains a Canvas element and loads main.js.

main.js obtains the Canvas context and draws a simple shape.

style.css contains the minimum CSS needed for the page.

The complete initial code is:

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>okoze</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <canvas id="canvas" width="400" height="300"></canvas>
  <script src="main.js"></script>
</body>
</html>

main.js

const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

ctx.fillRect(50, 50, 300, 200);

The code originally suggested by AI drew only the outline of a rectangle.

I changed it to a filled rectangle because the outline could easily be confused with the border of the Canvas itself.

style.css

canvas {
  border: 1px solid black;
}

The original code suggested by AI did not have a border around the Canvas.

I added one so that it is immediately clear where the Canvas is and how large it is.

These are small changes, but they are also examples of how I intend to work with AI.

AI writes code, but I decide whether the result actually makes sense.

Note

The code in this series is not necessarily the first code suggested by AI. I will make changes when I find that the generated code does not behave as I want or is difficult to understand.

At this point, I only want to confirm that I can create and edit the project using Visual Studio Code.

The first test is now Green.

I commit it.

Because this is the first commit, I also record the feature being implemented in the Git history.

git commit --allow-empty -m "🟧 1A Development environment"
git add -A
git commit -m "🟢 The project can be edited in VSCode"

The first commit marks the beginning of the feature, while the second records the first test becoming Green.

Starting the Development Server

Next, I start Live Server from Visual Studio Code.

The application opens in Chromium.

The browser displays the Canvas and the rectangle drawn by main.js.

The second test is now Green.

I commit it using the test itself as the commit message:

🟢 The Web Server can be started and the Canvas and a shape can be displayed in the browser

At this point, something else catches my attention.

The Canvas is currently a fixed size.

Eventually, I will probably want it to fill the available window and respond when the window is resized.

So I write down two more tests:

🔴 The Canvas can fill the available window
🔴 The Canvas can be resized when the window size changes

I could implement these now.

But I won't.

The feature I am currently implementing is the development environment.

These newly discovered requirements concern the layout and behavior of the Canvas, not the development environment itself.

For now, I will only record them.

Note

A newly discovered requirement does not necessarily have to be implemented immediately.

Recording it is often enough to prevent it from being forgotten.

If I start implementing every little thing I happen to notice, the list of things to do will keep growing, and this episode may never end.

For now, these tests remain Red.

Committing the Project

Finally, I push the project to the GitHub repository.

The project files are now visible in the repository.

The third test is now Green:

🟢 The project contents can be viewed in the GitHub repository

I commit this result as well.

The three original tests have now passed.

The two additional tests remain open:

🔴 The Canvas can fill the available window
🔴 The Canvas can be resized when the window size changes

They are recorded as work for a later episode.

The First Feature Is Complete

The feature

🟧 1A Development environment

is now complete.

This is a very small feature, but it demonstrates the development process I described in the first episode:

write a small specification
        ↓
write test cases
        ↓
implement
        ↓
Red → Green
        ↓
commit
        ↓
merge

The development environment itself is also deliberately small.

There is no framework, build system, or complicated development server.

I can:

  • edit the source code
  • run it in a browser
  • draw something on a Canvas
  • commit the result
  • view the project in GitHub

That is enough to start developing okoze.

There is another important point here.

During development, I discovered two additional requirements.

Instead of immediately implementing them, I recorded them as tests and continued working on the original feature.

This gives me a simple way to keep the scope of an episode under control.

The actual puzzle application has barely started yet.

But from the next episode onward, I can use this environment to start working on okoze itself.

Source Code, Live Demo, and Development Workflow

The source code for this episode is tagged:

episode-003

Code: episode-003

When a Git tag is pushed, a GitHub Actions workflow publishes the source code associated with that tag to GitHub Pages.

The live demo for this episode is therefore available at:

Live demo: okoze episode-003

If you are interested in how this works, see Publishing an Episode as a Web App with GitHub Pages.

Note

index.html has been modified for the live demo, including adding a title and other descriptive information.

A Little Repository Housekeeping

Before finishing, I add two files that are useful for an open-source project:

README.md
LICENSE

The project uses the MIT License.

These files are not part of the application itself, and there is nothing particularly interesting to say about them here.

I simply want the repository to have the basic information and licensing in place before development proceeds further.

Looking at the Git History

One reason I record the feature and tests in the commit history is that the development process becomes visible when looking at git log.

The final history for this episode looks approximately like this:

git log --oneline --reverse
ffce7aa 🟧 1A Development environment
75425a3 🟢 The project can be edited in VSCode
e6b2ad9 🟢 The Web Server can be started and the Canvas and a shape can be displayed in the browser
a8e76d1 🟢 The project contents can be viewed in the GitHub repository
ee693a0 (HEAD -> main, origin/main) doc: Add README and MIT license

The actual commit IDs will of course be different.

What I find interesting here is that the history itself tells a small story:

🟧 feature
   ↓
🟢 test
   ↓
🟢 test
   ↓
🟢 test

The code is not the only record of what happened.

The Git history also records how the feature was developed and which tests made it complete.

This is a small example, but I intend to continue using this style throughout the project.

Clone this wiki locally