Skip to content

Commit 256314a

Browse files
MpdreamzMpdreamz
committed
Update our README.md and introduce CONTRIBUTING.md
1 parent 9bd478c commit 256314a

File tree

3 files changed

+126
-120
lines changed

3 files changed

+126
-120
lines changed

‎CONTRIBUTING.MD‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Contributing
2+
3+
## Prerequisites
4+
5+
- [.NET 9.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/9.0)
6+
- [Node.js 22.13.1 (LTS)](https://nodejs.org/en/blog/release/v22.13.1)
7+
- [Aspire 9.4.1](https://learn.microsoft.com/en-us/dotnet/aspire/)
8+
```bash
9+
dotnet workload install aspire
10+
```
11+
12+
## Validate the fully assembled documentation
13+
14+
```bash
15+
dotnet run --project aspire
16+
```
17+
18+
Will spin up all our services and clone and build all the documentation sets.
19+
20+
```markdown
21+
dotnet run --project aspire -- --assume-cloned --skip-private-repositories
22+
```
23+
24+
`--asume-cloned` will assume a documentation set set is already cloned if available locally.
25+
26+
`--skip-private-repositories` will skip cloning private repositories. It will also inject our `docs-builder docs into the
27+
navigation. This allows us to validate new features' effect on the assembly process.
28+
29+
Our [Integration Tests](./tests-integration/Elastic.Assembler.IntegrationTests) use this exact command to validate the
30+
assembler builds.
31+
32+
## Continuously build all assets during development.
33+
34+
```shell
35+
./build.sh watch
36+
```
37+
38+
This will monitor code, cshtml template files & static files and reload the application
39+
if any changes.
40+
41+
Web assets are reloaded through `parcel watch` and don't require a recompilation.
42+
43+
Markdown files are refreshed automatically through livereload
44+
45+
Code or layout changes will relaunch the server automatically
46+
47+
# Release Process
48+
49+
This section outlines the process for releasing a new version of this project.
50+
51+
## Versioning
52+
53+
This project uses [Semantic Versioning](https://semver.org/) and its version is
54+
automatically determined by [release-drafter](https://github.com/release-drafter/release-drafter)
55+
based on the labels of the pull requests merged into the `main` branch.
56+
57+
See the [release-drafter configuration](./.github/release-drafter.yml) for more details.
58+
59+
## Creating a New Release
60+
61+
To create a new release trigger the [release](https://github.com/elastic/docs-builder/actions/workflows/release.yml) workflow on the `main` branch.
62+
63+
Every time a pull request is merged into the `main` branch, release-drafter will
64+
create a draft release or update the existing draft release in the [Releases](https://github.com/elastic/docs-builder/releases) page.
65+
66+
To create a new release you need to publish the existing draft release created by release-drafter.
67+
68+
> [!IMPORTANT]
69+
> Make sure the [release-drafter workflow](https://github.com/elastic/docs-builder/actions/workflows/release-drafter.yml) is finished before publishing the release.
70+
71+
> [!NOTE]
72+
> When a release is published, the [create-major-tag workflow](./.github/workflows/create-major-tag.yml)
73+
> will force push a new major tag in the format `vX` where `X` is the major version of the release.
74+
> For example, if the release is `1.2.3` was published, the workflow will force push a new tag `v1` on the same commit.

‎README.md‎

Lines changed: 51 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -2,84 +2,83 @@
22

33
[![ci](https://github.com/elastic/docs-builder/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/elastic/docs-builder/actions/workflows/ci.yml)
44

5-
You've reached the home of the latest incarnation of the documentation tooling.
5+
Distributed documentation tooling for a distributed company.
66

77
This repository is host to:
88

9-
* *`docs-builder`* command line tool to generate single doc-sets (13mb native code, no dependencies)
10-
* *`docs-assembler`* command line tool to assemble all the doc sets. (IN PROGRESS)
11-
* `elastic/docs-builder@main` Github Action to build and validate a repositories documentation
9+
* *`docs-builder`* command line tool to generate single doc-sets (native code, no dependencies)
10+
* *`docs-assembler`* command line tool to assemble all the doc sets.
1211

13-
## Command line interface
12+
## Distributed documentation
1413

15-
```bash
16-
$ docs-builder --help
17-
Usage: [command] [options...] [-h|--help] [--version]
18-
19-
Converts a source markdown folder or file to an output folder
20-
21-
Options:
22-
-p|--path <string?> Defaults to the`{pwd}/docs` folder (Default: null)
23-
-o|--output <string?> Defaults to `.artifacts/html` (Default: null)
24-
--path-prefix <string?> Specifies the path prefix for urls (Default: null)
25-
--force <bool?> Force a full rebuild of the destination folder (Default: null)
26-
27-
Commands:
28-
generate Converts a source markdown folder or file to an output folder
29-
serve Continuously serve a documentation folder at http://localhost:3000.
30-
diff validate Validates redirect rules have been applied to the current branch.
31-
File systems changes will be reflected without having to restart the server.
32-
```
14+
The main driver for folks writing documentation is `docs-builder`.
15+
This tool builds each repository in isolation and in addition produces a links.json file.
16+
17+
Each time a repository successfully builds on its respective main integration branch, the tool will update its links.json file.
18+
Example: [Elasticsearch's links.json](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic/elasticsearch/main/links.json) representing all linkable resources in the Elasticsearch repository.
19+
20+
The `docs-assembler` tool then assembles all the repositories in the [link-registry](https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/link-index.json) using their last known good commit.
3321

34-
In the near term native code will be published by CI for the following platforms
22+
This allows us to:
3523

36-
| OS | Architectures |
37-
|----------|---------------|
38-
| Windows | x64, Arm64 |
39-
| Linux | x64, Arm64 |
40-
| macOS | x64, Arm64 |
24+
* Validate outbound and inbound links ahead of time during `docs-builder` builds.
25+
* Documentation errors in one repository won't affect all the others.
26+
* Since we only build commits that have produced a `links.json` file the assembler is resilient to repositories having build failures on their integration branches.
4127

42-
And we'll invest time in making sure these are easily obtainable (`brew`, `winget`, `apt`)
4328

44-
For now you can run the tool locally through `docker run`
29+
## Installation
4530

31+
### Linux / OSX
4632
```bash
47-
docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" \
48-
ghcr.io/elastic/docs-builder:edge
33+
curl -sL https://ela.st/docs-builder-install | sh
4934
```
5035

51-
This ensures `.git`/`docs` and `.artifacts` (the default output directory) are mounted.
36+
### Windows
37+
```ps
38+
iex (New-Object System.Net.WebClient).DownloadString('https://ela.st/docs-builder-install-win')
39+
```
5240

53-
The tool will default to incremental compilation.
54-
Only the changed files on subsequent runs will be compiled unless you pass `--force`
55-
to force a new compilation.
41+
Installing through the script will download the latest version of the tool and make it available in your `PATH`.
5642

57-
```bash
58-
docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" \
59-
ghcr.io/elastic/docs-builder:edge --force
60-
```
43+
If you want to manually install the tool you can download the latest release from the [Releases Page](https://github.com/elastic/docs-builder/releases)
6144

62-
#### Live mode
45+
### Building locally
6346

64-
Through the `serve` command you can continuously and partially compile your documentation.
47+
Install [.NET 9.0](https://dotnet.microsoft.com/en-us/download/dotnet/9.0), then run:
6548

6649
```bash
67-
docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" \
68-
-p 3000:3000 ghcr.io/elastic/docs-builder:edge serve
50+
./build.sh publishbinaries
6951
```
52+
After which the locally built binaries will be available at:
7053

71-
Each page is compiled on demand as you browse http://localhost:3000 and is never cached so changes to files and
72-
navigation will always be reflected upon refresh.
54+
* **docs-builder**: `./.artifacts/publish/docs-builder/release/docs-builder`
55+
* **docs-assembler**: `./.artifacts/publish/docs-assembler/release/docs-assembler`
56+
57+
## Getting Started
7358

74-
Note the docker image is `linux-x86` and will be somewhat slower to invoke on OSX due to virtualization.
59+
Our [Documentation](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/locally) is the best place to learn how to start using the tool locally.
7560

61+
The TLDR, however, is
7662

77-
## Github Action
63+
* Running `docs-builder` from the root of any checkout with a `docs` folder will build the documentation.
64+
* Running `docs-builder` consecutively will only rebuild the documentation that has changed.
65+
* Running `docs-builder` with the `--force` flag will force a full rebuild of the documentation.
66+
* You can target different folders by passing a path to `docs-builder --path <path>`
67+
* Running `docs-builder serve` will provide a local server with live reloading.
68+
* You can leave this command running while you add/remove/rename files in your `docs` folder.
7869

79-
The `docs-builder` tool is available as github action.
8070

81-
Since it runs from a precompiled distroless image `~25mb` it's able to execute snappy. (no need to wait for building the tool itself)
8271

72+
#### Live mode
73+
74+
Through the `serve` command you can continuously and partially compile your documentation.
75+
76+
77+
## Github Action
78+
79+
The `docs-builder` tool is available as a GitHub action.
80+
81+
It runs as native code on a distroless image `~25mb` so there is little overhead invoking the tooling.
8382

8483
```yaml
8584
jobs:
@@ -129,74 +128,6 @@ If documentation is moved, renamed or deleted, `docs-builder` can verify if chan
129128

130129
---
131130

132-
## Run without docker
133-
134-
You can use the .NET CLI to publish a self-contained `docs-builder` native code
135-
binary. (On my M2 Pro mac the binary is currently 16mb)
136-
137-
Install [.NET 9.0](https://dotnet.microsoft.com/en-us/download/dotnet/9.0), then run:
138-
139-
```bash
140-
dotnet publish "src/docs-builder/docs-builder.csproj"
141-
```
142-
143-
The resulting binary `./.artifacts/publish/docs-builder/release/docs-builder` will run on machines without .NET installed.
144-
145-
# Performance
146-
147-
To test performance it's best to build the binary and run outside of docker:
148-
149-
For reference here's the `markitpy-doc` docset (50k markdown files) currently takes `14s` vs `several minutes` compared to
150-
existing surveyed tools
151-
152131
# Local Development
153132

154-
## Prerequisites
155-
156-
- [.NET 9.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/9.0)
157-
- [Node.js 22.13.1 (LTS)](https://nodejs.org/en/blog/release/v22.13.1)
158-
159-
160-
## Continuously build all assets during development.
161-
162-
```shell
163-
./build.sh watch
164-
```
165-
166-
This will monitor code, cshtml template files & static files and reload the application
167-
if any changes.
168-
169-
Web assets are reloaded through `parcel watch` and don't require a recompilation.
170-
171-
Markdown files are refreshed automatically through livereload
172-
173-
Code or layout changes will relaunch the server automatically
174-
175-
# Release Process
176-
177-
This section outlines the process for releasing a new version of this project.
178-
179-
## Versioning
180-
181-
This project uses [Semantic Versioning](https://semver.org/) and its version is
182-
automatically determined by [release-drafter](https://github.com/release-drafter/release-drafter)
183-
based on the labels of the pull requests merged into the `main` branch.
184-
185-
See the [release-drafter configuration](./.github/release-drafter.yml) for more details.
186-
187-
## Creating a New Release
188-
189-
To create a new release trigger the [release](https://github.com/elastic/docs-builder/actions/workflows/release.yml) workflow on the `main` branch.
190-
191-
Every time a pull request is merged into the `main` branch, release-drafter will
192-
create a draft release or update the existing draft release in the [Releases](https://github.com/elastic/docs-builder/releases) page.
193-
194-
To create a new release you need to publish the existing draft release created by release-drafter.
195-
196-
> [!IMPORTANT]
197-
> Make sure the [release-drafter workflow](https://github.com/elastic/docs-builder/actions/workflows/release-drafter.yml) is finished before publishing the release.
198-
199-
> [!NOTE]
200-
> When a release is published, the [create-major-tag workflow](./.github/workflows/create-major-tag.yml)
201-
> will force push a new major tag in the format `vX` where `X` is the major version of the release.
202-
> For example, if the release is `1.2.3` was published, the workflow will force push a new tag `v1` on the same commit.
133+
See [CONTRIBUTING.md](CONTRIBUTING.md) for more information on how to develop locally and contribute to the project.

‎docs-builder.sln‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "root", "root", "{94AC66E5-3
1313
dotnet-tools.json = dotnet-tools.json
1414
global.json = global.json
1515
Directory.Packages.props = Directory.Packages.props
16+
CONTRIBUTING.MD = CONTRIBUTING.MD
1617
EndProjectSection
1718
EndProject
1819
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{BE6011CC-1200-4957-B01F-FCCA10C5CF5A}"

0 commit comments

Comments
 (0)