Skip to content

Commit 857632e

Browse files
reakaleekreakaleek
authored
Merge branch 'main' into dependabot/npm_and_yarn/src/Elastic.Documentation.Site/zod-4.1.8
2 parents 8a4ee54 + 124ed2f commit 857632e

File tree

223 files changed

+7196
-2098
lines changed

Some content is hidden

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

223 files changed

+7196
-2098
lines changed

‎.github/actions/bootstrap/action.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ runs:
2424
run: |
2525
git config --global init.defaultBranch main
2626
27-
- uses: actions/setup-dotnet@v4
27+
- uses: actions/setup-dotnet@v5
2828
with:
2929
global-json-file: global.json
3030

‎.github/copilot-instructions.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# docs-builder
2+
3+
**ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
4+
5+
Elastic's distributed documentation tooling system built on .NET 9, consisting of:
6+
- **docs-builder**: CLI tool for building single documentation sets
7+
- **docs-assembler**: CLI tool for assembling multiple doc sets
8+
- Written in C# and F# with extensive Markdown processing capabilities
9+
10+
## Working Effectively
11+
12+
### Prerequisites and Setup
13+
Install these in order:
14+
```bash
15+
# Install .NET 9.0 SDK
16+
curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel 9.0
17+
export PATH="$HOME/.dotnet:$PATH"
18+
19+
# Restore .NET tools (required)
20+
dotnet tool restore
21+
22+
# Install Aspire workload (required for local development)
23+
dotnet workload install aspire
24+
```
25+
26+
### Build and Test Commands
27+
```bash
28+
# Basic build - takes 2 minutes. NEVER CANCEL. Set timeout to 180+ seconds.
29+
dotnet build
30+
31+
# Custom build system - takes 1.5 minutes. NEVER CANCEL. Set timeout to 120+ seconds.
32+
./build.sh
33+
34+
# Unit tests - takes 20 seconds. NEVER CANCEL. Set timeout to 60+ seconds.
35+
./build.sh unit-test
36+
37+
# Integration tests - takes 1 minute. NEVER CANCEL. Set timeout to 120+ seconds.
38+
# Note: May fail in sandboxed environments due to network/service dependencies
39+
./build.sh integrate
40+
41+
# Clean build artifacts
42+
./build.sh clean
43+
44+
# Format code - takes 1 minute. NEVER CANCEL. Set timeout to 120+ seconds.
45+
dotnet format
46+
47+
# Lint/format check - takes 1 minute. NEVER CANCEL. Set timeout to 120+ seconds.
48+
dotnet format --verify-no-changes
49+
```
50+
51+
### Node.js Dependencies (Documentation Site)
52+
```bash
53+
cd src/Elastic.Documentation.Site
54+
55+
# Install dependencies - takes 15 seconds
56+
npm ci
57+
58+
# Lint TypeScript/JavaScript - takes 2 seconds
59+
npm run lint
60+
61+
# Build web assets - takes 10 seconds
62+
npm run build
63+
64+
# Run tests
65+
npm run test
66+
```
67+
68+
### CLI Tools Usage
69+
```bash
70+
# Build documentation from ./docs folder - takes 15 seconds
71+
dotnet run --project src/tooling/docs-builder
72+
73+
# Serve with live reload at http://localhost:3000
74+
dotnet run --project src/tooling/docs-builder -- serve
75+
76+
# Get help for docs-builder
77+
dotnet run --project src/tooling/docs-builder -- --help
78+
79+
# Get help for docs-assembler
80+
dotnet run --project src/tooling/docs-assembler -- --help
81+
82+
# Validate assembler configuration - takes 15 seconds
83+
dotnet run --project src/tooling/docs-assembler -c release -- navigation validate
84+
```
85+
86+
### Local Development Orchestration
87+
```bash
88+
# Run full local environment with Aspire (requires network access)
89+
dotnet run --project aspire
90+
91+
# With options for local development
92+
dotnet run --project aspire -- --assume-cloned --skip-private-repositories
93+
94+
# Watch mode for continuous development - monitors file changes
95+
./build.sh watch
96+
```
97+
98+
## Validation
99+
100+
### Always run these before submitting changes:
101+
```bash
102+
# 1. Format code
103+
dotnet format
104+
105+
# 2. Build successfully
106+
./build.sh
107+
108+
# 3. Run unit tests
109+
./build.sh unit-test
110+
111+
# 4. Lint TypeScript/JavaScript
112+
cd src/Elastic.Documentation.Site && npm run lint
113+
```
114+
115+
### Testing Changes
116+
- **ALWAYS** test the docs-builder CLI after making changes to verify functionality
117+
- Test both building (`dotnet run --project src/tooling/docs-builder`) and serving (`dotnet run --project src/tooling/docs-builder -- serve`)
118+
- For markdown processing changes, build the repository's own docs to validate
119+
- For web components, build the npm assets and check output
120+
121+
## Common Tasks
122+
123+
### Key Project Structure
124+
```
125+
src/
126+
├── Elastic.Markdown/ # Core Markdown processing engine
127+
├── tooling/
128+
│ ├── docs-builder/ # Main CLI application
129+
│ └── docs-assembler/ # Assembly tool
130+
├── Elastic.Documentation.Site/ # Web rendering components (TypeScript/CSS)
131+
└── Elastic.Documentation.Configuration/ # Configuration handling
132+
133+
tests/
134+
├── Elastic.Markdown.Tests/ # C# unit tests
135+
├── authoring/ # F# authoring tests
136+
└── docs-assembler.Tests/ # Assembler tests
137+
138+
tests-integration/ # Integration tests
139+
docs/ # Repository documentation
140+
config/ # YAML configuration files
141+
```
142+
143+
### Adding New Features
144+
- **Markdown Extensions**: Add to `src/Elastic.Markdown/Myst/`
145+
- **CLI Commands**: Extend `src/tooling/docs-builder/Cli/` or `docs-assembler/Cli/`
146+
- **Web Components**: Add to `src/Elastic.Documentation.Site/`
147+
- **Configuration**: Modify `src/Elastic.Documentation.Configuration/`
148+
149+
### Important Files
150+
- `build/Targets.fs` - F# build script definitions
151+
- `docs-builder.sln` - Main solution file
152+
- `global.json` - .NET SDK version (9.0.100)
153+
- `Directory.Build.props` - MSBuild properties
154+
- `Directory.Packages.props` - Centralized package management
155+
- `dotnet-tools.json` - Required .NET tools
156+
157+
### Build Timing Expectations
158+
- **NEVER CANCEL** builds or tests - they may take longer than expected
159+
- Initial build: ~2 minutes
160+
- Incremental builds: ~30 seconds
161+
- Unit tests: ~20 seconds
162+
- Integration tests: ~1 minute (may fail without network access)
163+
- Format checking: ~1 minute
164+
- TypeScript build: ~10 seconds
165+
166+
### Environment Notes
167+
- Builds successfully on Ubuntu, macOS, and Windows
168+
- Integration tests require network access (may fail in sandboxed environments)
169+
- Uses both C# (.NET 9) and F# for different components
170+
- TypeScript/Node.js for web asset building
171+
- Self-hosting documentation demonstrating the tool's capabilities
172+
173+
### Documentation Updates
174+
When changing markdown syntax or rendering behavior, **always** update the documentation in the `/docs/` folder as this repository is self-documenting.
175+
176+
## Quick Reference
177+
178+
```bash
179+
# Full development setup from fresh clone
180+
curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel 9.0
181+
export PATH="$HOME/.dotnet:$PATH"
182+
dotnet tool restore
183+
dotnet workload install aspire
184+
cd src/Elastic.Documentation.Site && npm ci && cd ../..
185+
186+
# Build and validate changes
187+
dotnet format
188+
./build.sh
189+
./build.sh unit-test
190+
cd src/Elastic.Documentation.Site && npm run lint && npm run build
191+
192+
# Test CLI functionality
193+
dotnet run --project src/tooling/docs-builder
194+
dotnet run --project src/tooling/docs-builder -- serve
195+
```

‎.github/dependabot.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ updates:
1212
- package-ecosystem: npm
1313
directories:
1414
- '**/*'
15+
cooldown:
16+
default-days: 14
1517
schedule:
1618
interval: 'weekly'
1719
day: 'monday'

‎.github/updatecli/updatecli.d/versions.yml‎

Lines changed: 26 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -58,8 +58,8 @@ sources:
5858
token: '{{ requiredEnv "GITHUB_TOKEN" }}'
5959
username: '{{ requiredEnv "GITHUB_ACTOR" }}'
6060
versionfilter:
61-
kind: regex
62-
pattern: "v9.(\\d*).(\\d*)$"
61+
kind: semver
62+
pattern: "^9.0.0"
6363

6464
latest-edot-dotnet-version:
6565
name: Get latest release version for the elastic-otel-dotnet
@@ -303,7 +303,7 @@ targets:
303303
kind: yaml
304304
spec:
305305
file: config/versions.yml
306-
key: versioning_systems.edot_android.current
306+
key: versioning_systems.edot-android.current
307307

308308
update-docs-docset-collector:
309309
name: 'Update config/versions.yml edot-collector {{ source "latest-edot-collector-version" }}'
@@ -312,7 +312,7 @@ targets:
312312
kind: yaml
313313
spec:
314314
file: config/versions.yml
315-
key: versioning_systems.edot_collector.current
315+
key: $.versioning_systems.edot-collector.current
316316

317317
update-docs-docset-dotnet:
318318
name: 'Update config/versions.yml edot-dotnet {{ source "latest-edot-dotnet-version" }}'
@@ -321,7 +321,7 @@ targets:
321321
kind: yaml
322322
spec:
323323
file: config/versions.yml
324-
key: versioning_systems.edot_dotnet.current
324+
key: versioning_systems.edot-dotnet.current
325325

326326
update-docs-docset-ios:
327327
name: 'Update config/versions.yml edot-ios {{ source "latest-edot-ios-version" }}'
@@ -330,7 +330,7 @@ targets:
330330
kind: yaml
331331
spec:
332332
file: config/versions.yml
333-
key: versioning_systems.edot_ios.current
333+
key: versioning_systems.edot-ios.current
334334

335335
update-docs-docset-java:
336336
name: 'Update config/versions.yml edot-java {{ source "latest-edot-java-version" }}'
@@ -339,7 +339,7 @@ targets:
339339
kind: yaml
340340
spec:
341341
file: config/versions.yml
342-
key: versioning_systems.edot_java.current
342+
key: versioning_systems.edot-java.current
343343

344344
update-docs-docset-node:
345345
name: 'Update config/versions.yml edot-node {{ source "latest-edot-node-version" }}'
@@ -348,7 +348,7 @@ targets:
348348
kind: yaml
349349
spec:
350350
file: config/versions.yml
351-
key: versioning_systems.edot_node.current
351+
key: versioning_systems.edot-node.current
352352

353353
update-docs-docset-php:
354354
name: 'Update config/versions.yml edot-php {{ source "latest-edot-php-version" }}'
@@ -357,7 +357,7 @@ targets:
357357
kind: yaml
358358
spec:
359359
file: config/versions.yml
360-
key: versioning_systems.edot_php.current
360+
key: versioning_systems.edot-php.current
361361

362362
update-docs-docset-python:
363363
name: 'Update config/versions.yml edot-python {{ source "latest-edot-python-version" }}'
@@ -366,7 +366,7 @@ targets:
366366
kind: yaml
367367
spec:
368368
file: config/versions.yml
369-
key: versioning_systems.edot_python.current
369+
key: versioning_systems.edot-python.current
370370

371371
update-docs-docset-eck:
372372
name: 'Update config/versions.yml eck {{ source "latest-eck-version" }}'
@@ -396,73 +396,73 @@ targets:
396396
key: versioning_systems.curator.current
397397

398398
update-docs-docset-apm-agent-dotnet:
399-
name: 'Update config/versions.yml apm_agent_dotnet {{ source "latest-apm-agent-dotnet-version" }}'
399+
name: 'Update config/versions.yml apm-agent-dotnet {{ source "latest-apm-agent-dotnet-version" }}'
400400
scmid: githubConfig
401401
sourceid: latest-apm-agent-dotnet-version
402402
kind: yaml
403403
spec:
404404
file: config/versions.yml
405-
key: versioning_systems.apm_agent_dotnet.current
405+
key: versioning_systems.apm-agent-dotnet.current
406406

407407
update-docs-docset-apm-agent-go:
408-
name: 'Update config/versions.yml apm_agent_go {{ source "latest-apm-agent-go-version" }}'
408+
name: 'Update config/versions.yml apm-agent-go {{ source "latest-apm-agent-go-version" }}'
409409
scmid: githubConfig
410410
sourceid: latest-apm-agent-go-version
411411
kind: yaml
412412
spec:
413413
file: config/versions.yml
414-
key: versioning_systems.apm_agent_go.current
414+
key: versioning_systems.apm-agent-go.current
415415

416416
update-docs-docset-apm-agent-java:
417-
name: 'Update config/versions.yml apm_agent_java {{ source "latest-apm-agent-java-version" }}'
417+
name: 'Update config/versions.yml apm-agent-java {{ source "latest-apm-agent-java-version" }}'
418418
scmid: githubConfig
419419
sourceid: latest-apm-agent-java-version
420420
kind: yaml
421421
spec:
422422
file: config/versions.yml
423-
key: versioning_systems.apm_agent_java.current
423+
key: versioning_systems.apm-agent-java.current
424424

425425
update-docs-docset-apm-agent-node:
426-
name: 'Update config/versions.yml apm_agent_node {{ source "latest-apm-agent-node-version" }}'
426+
name: 'Update config/versions.yml apm-agent-node {{ source "latest-apm-agent-node-version" }}'
427427
scmid: githubConfig
428428
sourceid: latest-apm-agent-node-version
429429
kind: yaml
430430
spec:
431431
file: config/versions.yml
432-
key: versioning_systems.apm_agent_node.current
432+
key: versioning_systems.apm-agent-node.current
433433

434434
update-docs-docset-apm-agent-php:
435-
name: 'Update config/versions.yml apm_agent_php {{ source "latest-apm-agent-php-version" }}'
435+
name: 'Update config/versions.yml apm-agent-php {{ source "latest-apm-agent-php-version" }}'
436436
scmid: githubConfig
437437
sourceid: latest-apm-agent-php-version
438438
kind: yaml
439439
spec:
440440
file: config/versions.yml
441-
key: versioning_systems.apm_agent_php.current
441+
key: versioning_systems.apm-agent-php.current
442442

443443
update-docs-docset-apm-agent-python:
444-
name: 'Update config/versions.yml apm_agent_python {{ source "latest-apm-agent-python-version" }}'
444+
name: 'Update config/versions.yml apm-agent-python {{ source "latest-apm-agent-python-version" }}'
445445
scmid: githubConfig
446446
sourceid: latest-apm-agent-python-version
447447
kind: yaml
448448
spec:
449449
file: config/versions.yml
450-
key: versioning_systems.apm_agent_python.current
450+
key: versioning_systems.apm-agent-python.current
451451

452452
update-docs-docset-apm-agent-ruby:
453-
name: 'Update config/versions.yml apm_agent_ruby {{ source "latest-apm-agent-ruby-version" }}'
453+
name: 'Update config/versions.yml apm-agent-ruby {{ source "latest-apm-agent-ruby-version" }}'
454454
scmid: githubConfig
455455
sourceid: latest-apm-agent-ruby-version
456456
kind: yaml
457457
spec:
458458
file: config/versions.yml
459-
key: versioning_systems.apm_agent_ruby.current
459+
key: versioning_systems.apm-agent-ruby.current
460460

461461
update-docs-docset-apm-agent-rum:
462-
name: 'Update config/versions.yml apm_agent_rum {{ source "latest-apm-agent-rum-version" }}'
462+
name: 'Update config/versions.yml apm-agent-rum {{ source "latest-apm-agent-rum-version" }}'
463463
scmid: githubConfig
464464
sourceid: latest-apm-agent-rum-version
465465
kind: yaml
466466
spec:
467467
file: config/versions.yml
468-
key: versioning_systems.apm_agent_rum.current
468+
key: versioning_systems.apm-agent-rum-js.current

‎.github/workflows/auto-add-needs-triage-label.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ jobs:
1515
runs-on: ubuntu-latest
1616
steps:
1717
- name: Add needs triage label
18-
uses: actions/github-script@v7
18+
uses: actions/github-script@v8
1919
with:
2020
script: |
2121
github.rest.issues.addLabels({

0 commit comments

Comments
 (0)