Skip to content

Commit 320ae27

Browse files
DilumAluthgeDilumAluthge
authored
Reorganize the docs (#63)
1 parent f369eb9 commit 320ae27

3 files changed

Lines changed: 102 additions & 88 deletions

File tree

‎README.md‎

Lines changed: 21 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,103 +1,36 @@
1-
# VersionsJSONUtil
1+
# VersionsJSONUtil: Generate `versions.json` files that contain the list of Julia versions
22

3-
S3 URL: https://julialang-s3.julialang.org/bin/versions.json
3+
S3 URL:
4+
- v1: https://julialang-s3.julialang.org/bin/versions.json
5+
- v2: [coming soon][^1]
46

5-
More info: https://github.com/JuliaLang/julia/issues/33817
7+
[^1]: v2 is not available yet. When it becomes available, the S3 URL will *probably* be `https://julialang-s3.julialang.org/bin/versions.v2.json`
68

7-
## Triggering a rebuild
89

9-
To trigger a rebuild of the `versions.json` file and to upload it to S3, you need to manually trigger the `CI` workflow in this repo.
10-
You can either trigger it through the GitHub UI or via an authenticated HTTP request.
11-
12-
### GitHub's UI
13-
14-
![grafik](https://user-images.githubusercontent.com/20866761/127783220-fd8167db-5051-4a18-b70a-ea42085a7cb5.png)
15-
16-
### HTTP request
17-
18-
```bash
19-
curl \
20-
-u USERNAME:PERSONAL_ACCESS_TOKEN \
21-
-X POST \
22-
-H "Accept: application/vnd.github.v3+json" \
23-
https://api.github.com/repos/JuliaLang/VersionsJSONUtil.jl/actions/workflows/CI.yml/dispatches \
24-
-d '{"ref":"main"}'
25-
```
26-
27-
Replace `USERNAME` with your GitHub username, and `PERSONAL_ACCESS_TOKEN` with a [personal access token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `repo` scope.
28-
29-
**Note that it is not possible to restrict personal access tokens to individual repos.**
30-
**The token will have access to all repositories your GH account has access to.**
31-
**Consider using a [machine user](https://docs.github.com/en/developers/overview/managing-deploy-keys#machine-users) solely created for this purpose.**
32-
33-
For more info, check the [GitHub Docs](https://docs.github.com/en/rest/reference/actions#create-a-workflow-dispatch-event).
34-
35-
## Adding a new platform
36-
37-
1. Add the version that introduces the platform to the `download_urls` dictionary in [`test/runtests.jl`](test/runtests.jl).
38-
2. Add the platform the `julia_platforms` in [`src/VersionsJSONUtil.jl`](src/VersionsJSONUtil.jl).
39-
3. Add any missing methods such as `tar_os` until all tests for the new platform pass.
40-
41-
### Example
42-
43-
For an example, adding the M1 MacOS binaries takes the following additions:
44-
45-
#### `test/runtests.jl`
46-
47-
```julia
48-
const download_urls = Dict(
49-
v"1.7.0-beta3" => Dict(
50-
MacOS(:aarch64) => "https://julialang-s3.julialang.org/bin/mac/aarch64/1.7/julia-1.7.0-beta3-macaarch64.dmg",
51-
),
52-
...
53-
)
54-
```
55-
56-
#### `src/VersionsJSONUtil.jl`
57-
58-
```julia
59-
julia_platforms = [
60-
...
61-
MacOS(:aarch64),
62-
...
63-
]
64-
```
65-
66-
and changing `tar_os(p::MacOS)` from
67-
68-
```julia
69-
tar_os(p::MacOS) = "mac$(wordsize(p))"
70-
```
71-
72-
to
73-
74-
```julia
75-
function tar_os(p::MacOS)
76-
if arch(p) == :aarch64
77-
return "macaarch$(wordsize(p))"
78-
else
79-
return "mac$(wordsize(p))"
80-
end
81-
end
82-
```
8310

8411
## JSON Schema
8512

8613
[`schema.json`](schema.json) contains a [JSON Schema](https://json-schema.org/) for the `versions.json` file.
8714

8815
It can be used to validate the versions file or to [generate code](https://json-schema.org/implementations.html) from the schema.
8916

90-
## Tools using version.json
17+
## Downstream tools using `versions.json`
18+
19+
This is a (not necessarily complete) list of known tools that make use of `versions.json`.
20+
If you maintain such a tool, please make a PR to add it to this list.
21+
This allows us to check if changes might break downstream tooling.
22+
23+
- [abelsiqueira/jill](https://github.com/abelsiqueira/jill): A Julia installer written in Bash.
24+
- [johnnychen94/jill.py](https://github.com/johnnychen94/jill.py): A Julia installer written in Python.
25+
- [julia-actions/setup-julia](https://github.com/julia-actions/setup-julia): Installs Julia in GitHub Actions CI jobs.
26+
- [JuliaLang/Juliaup](https://github.com/JuliaLang/juliaup): Julia installer and version manager[^2]
27+
28+
[^2]: This also means that every tool that uses Juliaup is thus also downstream of `versions.json`.
9129

92-
This is an (incomplete) list of tools that make use of the published `versions.json`.
93-
If you maintain such a tool, consider adding info about it in this list.
94-
This allows us to verify if changes might affect downstream tooling.
30+
## Devdocs
9531

96-
- [julia-actions/setup-julia](https://github.com/julia-actions/setup-julia)
97-
- [johnnychen94/jill.py](https://github.com/johnnychen94/jill.py): a Julia installer written in Python
98-
- [abelsiqueira/jill](https://github.com/abelsiqueira/jill): a Julia installer
99-
- [Juliaup](https://github.com/JuliaLang/juliaup): Julia installer and version multiplexer
32+
See [`./devdocs/README.md`](./devdocs/README.md).
10033

101-
## Third Party Notice
34+
## Background and motivation
10235

103-
The [schema](schema.json) was generated with [quicktype.io](https://app.quicktype.io/#l=schema).
36+
This issue provides background info that explains the motivation: https://github.com/JuliaLang/julia/issues/33817

‎THIRD_PARTY_NOTICE.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Third Party Notice
2+
3+
The [schema](schema.json) was generated with [quicktype.io](https://app.quicktype.io/#l=schema).

‎devdocs/README.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Devdocs
2+
3+
## Triggering a rebuild
4+
5+
To trigger a rebuild of the `versions.json` file and to upload it to S3, you need to manually trigger the `CI` workflow in this repo.
6+
You can either trigger it through the GitHub UI or via an authenticated HTTP request.
7+
8+
### GitHub's UI
9+
10+
![grafik](https://user-images.githubusercontent.com/20866761/127783220-fd8167db-5051-4a18-b70a-ea42085a7cb5.png)
11+
12+
### HTTP request
13+
14+
```bash
15+
curl \
16+
-u USERNAME:PERSONAL_ACCESS_TOKEN \
17+
-X POST \
18+
-H "Accept: application/vnd.github.v3+json" \
19+
https://api.github.com/repos/JuliaLang/VersionsJSONUtil.jl/actions/workflows/CI.yml/dispatches \
20+
-d '{"ref":"main"}'
21+
```
22+
23+
Replace `USERNAME` with your GitHub username, and `PERSONAL_ACCESS_TOKEN` with a [personal access token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `repo` scope.
24+
25+
**Note that it is not possible to restrict personal access tokens to individual repos.**
26+
**The token will have access to all repositories your GH account has access to.**
27+
**Consider using a [machine user](https://docs.github.com/en/developers/overview/managing-deploy-keys#machine-users) solely created for this purpose.**
28+
29+
For more info, check the [GitHub Docs](https://docs.github.com/en/rest/reference/actions#create-a-workflow-dispatch-event).
30+
31+
## Adding a new platform
32+
33+
1. Add the version that introduces the platform to the `download_urls` dictionary in [`test/runtests.jl`](test/runtests.jl).
34+
2. Add the platform the `julia_platforms` in [`src/VersionsJSONUtil.jl`](src/VersionsJSONUtil.jl).
35+
3. Add any missing methods such as `tar_os` until all tests for the new platform pass.
36+
37+
### Example
38+
39+
For an example, adding the M1 MacOS binaries takes the following additions:
40+
41+
#### `test/runtests.jl`
42+
43+
```julia
44+
const download_urls = Dict(
45+
v"1.7.0-beta3" => Dict(
46+
MacOS(:aarch64) => "https://julialang-s3.julialang.org/bin/mac/aarch64/1.7/julia-1.7.0-beta3-macaarch64.dmg",
47+
),
48+
...
49+
)
50+
```
51+
52+
#### `src/VersionsJSONUtil.jl`
53+
54+
```julia
55+
julia_platforms = [
56+
...
57+
MacOS(:aarch64),
58+
...
59+
]
60+
```
61+
62+
and changing `tar_os(p::MacOS)` from
63+
64+
```julia
65+
tar_os(p::MacOS) = "mac$(wordsize(p))"
66+
```
67+
68+
to
69+
70+
```julia
71+
function tar_os(p::MacOS)
72+
if arch(p) == :aarch64
73+
return "macaarch$(wordsize(p))"
74+
else
75+
return "mac$(wordsize(p))"
76+
end
77+
end
78+
```

0 commit comments

Comments
 (0)