Skip to content

Commit 02e4351

Browse files
brunoborgesCopilot
brunoborges
and
Copilot
committed
Make JSON files the source of truth, generate HTML at build time
- Remove 86 generated HTML detail pages from version control - Remove data/snippets.json from version control (now generated) - Add .gitignore for all generated files - Update generate.py to also rebuild data/snippets.json - Add .github/copilot-instructions.md documenting the JSON-first workflow - Add .github/ISSUE_TEMPLATE/new-pattern.yml for pattern submissions Workflow: edit category/slug.json → run python3 generate.py → deploy Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 74819ab commit 02e4351

File tree

91 files changed

+275
-31420
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

91 files changed

+275
-31420
lines changed

‎.github/ISSUE_TEMPLATE/new-pattern.yml‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
name: New Pattern Submission
3+
description: Submit a new modern Java pattern
4+
title: "[Pattern] "
5+
labels: ["new-pattern"]
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: |
10+
## How to submit a new pattern
11+
12+
Patterns are defined as **JSON files** in category subfolders.
13+
Please provide the information below and we'll create the JSON file,
14+
or submit a PR with the JSON file directly.
15+
16+
- type: dropdown
17+
id: category
18+
attributes:
19+
label: Category
20+
options:
21+
- language
22+
- collections
23+
- strings
24+
- streams
25+
- concurrency
26+
- io
27+
- errors
28+
- datetime
29+
- security
30+
- tooling
31+
validations:
32+
required: true
33+
34+
- type: input
35+
id: slug
36+
attributes:
37+
label: Slug
38+
description: "URL-friendly identifier (e.g., `type-inference-with-var`)"
39+
placeholder: "my-pattern-name"
40+
validations:
41+
required: true
42+
43+
- type: input
44+
id: title
45+
attributes:
46+
label: Title
47+
description: "Human-readable title"
48+
placeholder: "Type inference with var"
49+
validations:
50+
required: true
51+
52+
- type: dropdown
53+
id: difficulty
54+
attributes:
55+
label: Difficulty
56+
options:
57+
- beginner
58+
- intermediate
59+
- advanced
60+
validations:
61+
required: true
62+
63+
- type: input
64+
id: jdk-version
65+
attributes:
66+
label: Since JDK
67+
description: "JDK version where this feature was introduced"
68+
placeholder: "21"
69+
validations:
70+
required: true
71+
72+
- type: textarea
73+
id: summary
74+
attributes:
75+
label: Summary
76+
description: "One-line description of the pattern"
77+
placeholder: "Use var for local variable type inference — less noise, same safety."
78+
validations:
79+
required: true
80+
81+
- type: input
82+
id: old-label
83+
attributes:
84+
label: Old code label
85+
placeholder: "Java 8"
86+
validations:
87+
required: true
88+
89+
- type: textarea
90+
id: old-code
91+
attributes:
92+
label: Old code
93+
description: "The legacy way of doing it"
94+
render: java
95+
validations:
96+
required: true
97+
98+
- type: input
99+
id: modern-label
100+
attributes:
101+
label: Modern code label
102+
placeholder: "Java 21+"
103+
validations:
104+
required: true
105+
106+
- type: textarea
107+
id: modern-code
108+
attributes:
109+
label: Modern code
110+
description: "The modern way of doing it"
111+
render: java
112+
validations:
113+
required: true
114+
115+
- type: textarea
116+
id: explanation
117+
attributes:
118+
label: Explanation
119+
description: "How it works — one or two paragraphs"
120+
validations:
121+
required: true
122+
123+
- type: textarea
124+
id: why-modern-wins
125+
attributes:
126+
label: Why the modern way wins
127+
description: |
128+
Provide exactly 3 reasons. Use this format:
129+
```
130+
⚡ Less boilerplate — No need to repeat complex types.
131+
👁 Better readability — Focus on values, not type declarations.
132+
🔒 Still type-safe — Compiler infers and enforces the exact type.
133+
```
134+
validations:
135+
required: true

‎.github/copilot-instructions.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Copilot Instructions for java.evolved
2+
3+
## Project Overview
4+
5+
This is a static site showcasing modern Java patterns vs legacy approaches.
6+
It is hosted on GitHub Pages at https://javaevolved.github.io.
7+
8+
## Architecture
9+
10+
### Source of Truth: JSON Files
11+
12+
Each pattern is defined as a JSON file in its **category subfolder**:
13+
14+
```
15+
language/type-inference-with-var.json
16+
collections/immutable-list-creation.json
17+
streams/stream-tolist.json
18+
...
19+
```
20+
21+
**Categories:** `language`, `collections`, `strings`, `streams`, `concurrency`, `io`, `errors`, `datetime`, `security`, `tooling`
22+
23+
### Generated Files (DO NOT EDIT)
24+
25+
The following are **generated by `generate.py`** and must not be edited directly:
26+
27+
- `language/*.html`, `collections/*.html`, etc. — detail pages
28+
- `data/snippets.json` — aggregated search index
29+
30+
Run `python3 generate.py` to rebuild all generated files from the JSON sources.
31+
32+
### Manually Maintained Files
33+
34+
- `index.html` — homepage with preview cards (must be updated manually when adding/removing patterns)
35+
- `app.js` — client-side search, filtering, code highlighting
36+
- `styles.css` — all styling
37+
- `slug-template.html` — reference template (actual generation is in `generate.py`)
38+
39+
## JSON Snippet Schema
40+
41+
Each `category/slug.json` file has this structure:
42+
43+
```json
44+
{
45+
"id": 1,
46+
"slug": "type-inference-with-var",
47+
"title": "Type inference with var",
48+
"category": "language",
49+
"difficulty": "beginner|intermediate|advanced",
50+
"jdkVersion": "10",
51+
"oldLabel": "Java 8",
52+
"modernLabel": "Java 10+",
53+
"oldApproach": "Explicit Types",
54+
"modernApproach": "var keyword",
55+
"oldCode": "// old way...",
56+
"modernCode": "// modern way...",
57+
"summary": "One-line description.",
58+
"explanation": "How it works paragraph.",
59+
"whyModernWins": [
60+
{ "icon": "⚡", "title": "Short title", "desc": "One sentence." },
61+
{ "icon": "👁", "title": "Short title", "desc": "One sentence." },
62+
{ "icon": "🔒", "title": "Short title", "desc": "One sentence." }
63+
],
64+
"support": "Widely available since JDK 10 (March 2018)",
65+
"prev": "category/slug-of-previous",
66+
"next": "category/slug-of-next",
67+
"related": [
68+
"category/slug-1",
69+
"category/slug-2",
70+
"category/slug-3"
71+
]
72+
}
73+
```
74+
75+
### Key Rules
76+
77+
- `slug` must match the filename (without `.json`)
78+
- `category` must match the parent folder name
79+
- `whyModernWins` must have exactly **3** entries
80+
- `related` must have exactly **3** entries (as `category/slug` paths)
81+
- `prev`/`next` are `category/slug` paths or `null` for first/last
82+
- Code in `oldCode`/`modernCode` uses `\n` for newlines
83+
84+
## Category Display Names
85+
86+
| ID | Display |
87+
|----|---------|
88+
| `language` | Language |
89+
| `collections` | Collections |
90+
| `strings` | Strings |
91+
| `streams` | Streams |
92+
| `concurrency` | Concurrency |
93+
| `io` | I/O |
94+
| `errors` | Errors |
95+
| `datetime` | Date/Time |
96+
| `security` | Security |
97+
| `tooling` | Tooling |
98+
99+
## Adding a New Pattern
100+
101+
1. Create `category/new-slug.json` with all required fields
102+
2. Update `prev`/`next` in the adjacent patterns' JSON files
103+
3. Add a preview card in `index.html`
104+
4. Run `python3 generate.py`
105+
106+
## Local Development
107+
108+
```bash
109+
python3 generate.py # Build HTML pages + snippets.json
110+
python3 -m http.server 8090 # Serve locally
111+
```

‎.gitignore‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Generated HTML detail pages (built by generate.py from JSON sources)
2+
language/*.html
3+
collections/*.html
4+
strings/*.html
5+
streams/*.html
6+
concurrency/*.html
7+
io/*.html
8+
errors/*.html
9+
datetime/*.html
10+
security/*.html
11+
tooling/*.html
12+
13+
# Generated aggregate file (built by generate.py from individual JSON sources)
14+
data/snippets.json

0 commit comments

Comments
 (0)