Skip to content

Commit 1c8db0d

Browse files
timzsucodex
timzsu
and
codex
authored
docs: polish first release documentation (#3)
* docs: polish first release documentation Co-Authored-By: Codex <codex@openai.com> Signed-off-by: Zhengyuan Su <su.zhengyuan@u.nus.edu> * docs: align release docs with FlowMesh Co-Authored-By: Codex <codex@openai.com> Signed-off-by: Zhengyuan Su <su.zhengyuan@u.nus.edu> * docs: route agent guidance through focused docs Co-Authored-By: Codex <codex@openai.com> Signed-off-by: Zhengyuan Su <su.zhengyuan@u.nus.edu> * docs: fix release doc alignment gaps Co-Authored-By: Codex <codex@openai.com> Signed-off-by: Zhengyuan Su <su.zhengyuan@u.nus.edu> * docs: close release documentation alignment gaps Co-Authored-By: Codex <codex@openai.com> Signed-off-by: Zhengyuan Su <su.zhengyuan@u.nus.edu> * docs: address release doc review comments Co-Authored-By: Codex <codex@openai.com> Signed-off-by: Zhengyuan Su <su.zhengyuan@u.nus.edu> * docs: clarify agent guidance structure Co-Authored-By: Codex <codex@openai.com> Signed-off-by: Zhengyuan Su <su.zhengyuan@u.nus.edu> --------- Signed-off-by: Zhengyuan Su <su.zhengyuan@u.nus.edu> Co-authored-by: Codex <codex@openai.com>
1 parent 05ea926 commit 1c8db0d

31 files changed

Lines changed: 981 additions & 396 deletions

‎.github/ISSUE_TEMPLATE/100-bug-report.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ body:
88
attributes:
99
value: >
1010
Before submitting, please search
11-
[existing issues](https://github.com/mlsys-io/lumilake/issues?q=is%3Aissue+sort%3Acreated-desc+)
11+
[existing issues](https://github.com/mlsys-io/lumilake_OSS/issues?q=is%3Aissue+sort%3Acreated-desc+)
1212
to avoid duplicates.
1313
1414
- type: dropdown
@@ -20,9 +20,11 @@ body:
2020
- Server / API routes
2121
- Runtime / scheduler / optimizer
2222
- Ops / operators
23+
- SDK
2324
- CLI (lumilake)
2425
- Deploy / Docker
2526
- Graphs / YAML / n8n parser
27+
- Hooks / plugins
2628
- Documentation
2729
- Other
2830
validations:

‎.github/ISSUE_TEMPLATE/200-deployment.yml‎

Lines changed: 45 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,80 @@
1-
name: Deployment issue
2-
description: Something went wrong with `lumilake deploy up/down/reset` or the Docker stack.
1+
name: Deployment / Installation
2+
description: Report an issue with installing or deploying Lumilake.
33
title: "[Deploy]: "
4-
labels: ["deploy"]
4+
labels: ["deployment"]
55

66
body:
7+
- type: markdown
8+
attributes:
9+
value: >
10+
Before submitting, please search
11+
[existing issues](https://github.com/mlsys-io/lumilake_OSS/issues?q=is%3Aissue+sort%3Acreated-desc+)
12+
to avoid duplicates.
13+
714
- type: dropdown
8-
id: mode
15+
id: deployment
916
attributes:
10-
label: Deploy mode
17+
label: Deployment method
1118
options:
12-
- lumid.data
13-
- Direct PostgreSQL + S3
14-
- Server only
19+
- Local (uv / pip)
20+
- Docker Compose (dev)
21+
- Bundled FlowMesh stack
22+
- External FlowMesh
23+
- Other
1524
validations:
1625
required: true
1726

18-
- type: textarea
27+
- type: dropdown
28+
id: data_plane
1929
attributes:
20-
label: Command and output
21-
description: |
22-
Paste the exact command and full output (wrap in triple-backticks).
23-
placeholder: |
24-
```
25-
$ uv run lumilake deploy up
26-
[deploy] ...
27-
```
30+
label: Data plane
31+
options:
32+
- lumid.data
33+
- Direct PostgreSQL + S3-compatible storage
34+
- Not configured yet
35+
- Multiple / unclear
2836
validations:
2937
required: true
3038

3139
- type: textarea
3240
attributes:
33-
label: .env (redacted)
41+
label: Describe the issue
3442
description: |
35-
Your ``.env`` with secrets redacted.
43+
What went wrong during installation or deployment?
44+
Include the commands you ran and the full error output.
3645
placeholder: |
37-
```dotenv
38-
LUMILAKE_SERVER_PORT="9000"
39-
LUMILAKE_RUNTIME_ORCHESTRATOR_URL="http://127.0.0.1:18000"
40-
LUMID_DATA_URL="http://127.0.0.1:9102"
46+
Steps to reproduce:
47+
1. ...
48+
49+
```
50+
Error output
4151
```
4252
validations:
4353
required: true
4454

45-
- type: textarea
46-
attributes:
47-
label: Container status and logs
48-
description: |
49-
Output of ``docker ps --filter name=lumilake`` plus
50-
relevant ``docker logs <container>`` excerpts.
51-
5255
- type: textarea
5356
attributes:
5457
label: Environment
58+
description: >
59+
Lumilake version/commit, OS, Docker version, Docker Compose version,
60+
Python version, and runtime/data-plane mode.
5561
value: |
5662
- Lumilake version:
5763
- OS:
5864
- Docker version:
5965
- Docker Compose version:
66+
- Python version:
67+
- Runtime / data plane:
6068
validations:
6169
required: true
6270

71+
- type: textarea
72+
attributes:
73+
label: Relevant config / logs
74+
description: >
75+
Paste relevant .env settings with secrets redacted, container status,
76+
or logs. Use triple-backtick blocks.
77+
6378
- type: checkboxes
6479
attributes:
6580
label: Before submitting

‎.github/ISSUE_TEMPLATE/300-feature-request.yml‎

Lines changed: 41 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,62 @@
11
name: Feature request
2-
description: Suggest a new capability for Lumilake.
2+
description: Propose a new feature or enhancement.
33
title: "[Feature]: "
4-
labels: ["enhancement"]
4+
labels: ["feature request"]
55

66
body:
7+
- type: markdown
8+
attributes:
9+
value: >
10+
Before submitting, please search
11+
[existing issues](https://github.com/mlsys-io/lumilake_OSS/issues?q=is%3Aissue+sort%3Acreated-desc+)
12+
to avoid duplicates.
13+
14+
- type: dropdown
15+
id: component
16+
attributes:
17+
label: Component
18+
description: Which component does this feature relate to?
19+
options:
20+
- Server / API routes
21+
- Runtime / scheduler / optimizer
22+
- Ops / operators
23+
- SDK
24+
- CLI
25+
- Deploy / Docker
26+
- Graphs / YAML / n8n parser
27+
- Hooks / plugins
28+
- Other
29+
validations:
30+
required: true
31+
732
- type: textarea
833
attributes:
9-
label: Problem
10-
description: |
11-
What are you trying to do today and why is it hard?
34+
label: Motivation
35+
description: >
36+
What problem does this solve? Is it related to a specific workflow or
37+
use case? e.g., "When running multi-stage data workflows, I need X because..."
1238
validations:
1339
required: true
1440

1541
- type: textarea
1642
attributes:
1743
label: Proposed solution
18-
description: |
19-
How would you like it to work? Sketch an API / CLI shape if helpful.
44+
description: >
45+
A clear description of what you'd like to happen.
2046
validations:
2147
required: true
2248

2349
- type: textarea
2450
attributes:
2551
label: Alternatives considered
26-
description: |
27-
Workarounds you've tried, or alternate designs you considered.
52+
description: >
53+
Any alternative solutions or workarounds you've considered.
54+
55+
- type: textarea
56+
attributes:
57+
label: Additional context
58+
description: >
59+
Any other context, mockups, or examples.
2860
2961
- type: checkboxes
3062
attributes:

‎.github/ISSUE_TEMPLATE/400-new-optimizer.yml‎

Lines changed: 37 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,63 @@
11
name: New optimizer strategy
22
description: Propose a new scheduling / optimization strategy.
33
title: "[Optimizer]: "
4-
labels: ["optimizer"]
4+
labels: ["optimizer", "feature request"]
55

66
body:
7+
- type: markdown
8+
attributes:
9+
value: >
10+
Lumilake currently ships HALO in-tree. Custom optimizers can also be
11+
registered as Lumilake plugins.
12+
713
- type: input
814
id: name
915
attributes:
1016
label: Optimizer name
11-
description: |
12-
e.g. ``halo-v2``, ``cost-greedy``, ``spot-aware``.
17+
description: >
18+
Name of the proposed optimizer and the scheduling approach it uses
19+
(e.g. "spot-aware cost optimizer").
1320
validations:
1421
required: true
1522

1623
- type: textarea
1724
attributes:
1825
label: Motivation
19-
description: |
20-
What scheduling problem does this solve that the existing strategies
21-
(``dummy``, ``halo``) don't handle well?
26+
description: >
27+
What use case does this enable? Why can't HALO or an existing plugin
28+
optimizer cover it?
2229
validations:
2330
required: true
2431

2532
- type: textarea
2633
attributes:
27-
label: Approach
28-
description: |
29-
Short design sketch. How does the planner build its plan? What signals
30-
from the runtime does it use? What's the complexity?
34+
label: Expected input / output
35+
description: >
36+
Describe the runtime graph shape, worker/resource signals, data-profile
37+
inputs, and expected schedule output. A sample workflow YAML snippet is helpful.
38+
placeholder: |
39+
```yaml
40+
nodes:
41+
...
42+
```
43+
44+
- type: dropdown
45+
id: plugin
46+
attributes:
47+
label: Should this be a plugin?
48+
options:
49+
- "Yes"
50+
- "No"
51+
- Depends on design
3152
validations:
3253
required: true
3354

55+
- type: textarea
56+
attributes:
57+
label: Additional context
58+
description: >
59+
Links to related papers, benchmarks, workloads, or existing implementations.
60+
3461
- type: checkboxes
3562
attributes:
3663
label: Before submitting

‎.github/ISSUE_TEMPLATE/500-documentation.yml‎

Lines changed: 12 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,29 @@
11
name: Documentation
2-
description: Something in the docs, README, or CONTRIBUTING is unclear, wrong, or missing.
3-
title: "[Docs]: "
2+
description: Report a documentation issue or suggest improvements.
3+
title: "[Doc]: "
44
labels: ["documentation"]
55

66
body:
7-
- type: input
8-
id: location
7+
- type: markdown
98
attributes:
10-
label: Where
11-
description: |
12-
Path to the file, or URL of the page. e.g. ``README.md``, ``CONTRIBUTING.md``, ``CLAUDE.md``, ``docs/``.
13-
validations:
14-
required: true
9+
value: >
10+
Before submitting, please search
11+
[existing issues](https://github.com/mlsys-io/lumilake_OSS/issues?q=is%3Aissue+sort%3Acreated-desc+)
12+
to avoid duplicates.
1513
1614
- type: textarea
1715
attributes:
18-
label: What's wrong or missing?
19-
description: |
20-
Quote the specific text if it's misleading, or describe what you
21-
were looking for and couldn't find.
16+
label: Describe the issue
17+
description: >
18+
What is missing, incorrect, or unclear in the documentation?
2219
validations:
2320
required: true
2421

2522
- type: textarea
2623
attributes:
2724
label: Suggested fix
28-
description: |
29-
Proposed replacement text or new section outline, if you have one.
25+
description: >
26+
How could the documentation be improved?
3027
3128
- type: checkboxes
3229
attributes:

‎.github/ISSUE_TEMPLATE/600-performance.yml‎

Lines changed: 23 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,44 @@
1-
name: Performance issue
2-
description: A submission, schedule, or execution is unexpectedly slow / expensive.
3-
title: "[Perf]: "
1+
name: Performance discussion
2+
description: Report a performance regression or propose an optimization.
3+
title: "[Performance]: "
44
labels: ["performance"]
55

66
body:
7+
- type: markdown
8+
attributes:
9+
value: >
10+
Before submitting, please search
11+
[existing issues](https://github.com/mlsys-io/lumilake_OSS/issues?q=is%3Aissue+sort%3Acreated-desc+)
12+
to avoid duplicates.
13+
714
- type: dropdown
8-
id: surface
15+
id: category
916
attributes:
10-
label: Where is the slowness?
17+
label: Category
1118
options:
12-
- /jobs/preview (graph compile)
13-
- /jobs (submission + first schedule)
14-
- Scheduler (HALO / dummy optimizer)
15-
- Data profiling
16-
- Output dump at finalize
17-
- FlowMesh dispatch / worker assignment
18-
- Other
19+
- Performance regression
20+
- Optimization proposal
21+
- Benchmarking / profiling
1922
validations:
2023
required: true
2124

2225
- type: textarea
2326
attributes:
24-
label: Workload
27+
label: Description
2528
description: |
26-
A minimal YAML workflow (or CLI command) that reproduces the slowness.
29+
For regressions: provide before/after measurements, the commit or version
30+
where regression started, and the workflow used to benchmark.
31+
32+
For proposals: describe the bottleneck and your proposed optimization.
2733
validations:
2834
required: true
2935

30-
- type: textarea
31-
attributes:
32-
label: Observed timing
33-
description: |
34-
Paste wall-clock numbers or profile snapshots. Compare against what
35-
you expected if possible.
36-
3736
- type: textarea
3837
attributes:
3938
label: Environment
40-
value: |
41-
- Lumilake version:
42-
- Optimizer: (dummy / halo / ...)
43-
- CPU / GPU:
44-
- Compute DB size (rough):
45-
validations:
46-
required: true
39+
description: >
40+
Lumilake version, hardware (CPU/GPU), runtime mode, data-plane mode,
41+
worker count, and any relevant config.
4742
4843
- type: checkboxes
4944
attributes:

0 commit comments

Comments
 (0)