Skip to content

Commit 1809fcc

Browse files
alirana01alirana01
committed
resolving review comments
1 parent 142c85a commit 1809fcc

1 file changed

Lines changed: 91 additions & 72 deletions

File tree

‎docs/src/MAINTENANCE.md‎

Lines changed: 91 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,83 @@ This document provides comprehensive guidance for maintaining the various distri
2020
- [Maintenance Checklists](#maintenance-checklists)
2121
- [Secrets Reference](#secrets-reference)
2222

23+
The checklists and secrets reference below are the most frequently used part of this guide; the detailed sections that follow give context for each component.
24+
25+
---
26+
27+
## Maintenance Checklists
28+
29+
### After Each Release
30+
31+
- [ ] Verify correct version of EIM and offline installer archives is on dl.espressif
32+
- [ ] Verify Homebrew formula updated automatically (check https://github.com/espressif/homebrew-eim)
33+
- [ ] Verify WinGet PR created (check https://github.com/microsoft/winget-pkgs/pulls)
34+
- [ ] Verify WinGet PR merged (may take 1-3 days for Microsoft review)
35+
- [ ] Verify APT repository updated (`apt-cache policy eim`)
36+
- [ ] Verify RPM repository updated (`dnf info eim`)
37+
- [ ] Verify Scoop manifests attached to release (when Scoop workflow is enabled)
38+
- [ ] Test Docker image with new release
39+
40+
### Monthly Maintenance
41+
42+
- [ ] Check Scoop manifest template versions against upstream:
43+
```bash
44+
curl -s https://raw.githubusercontent.com/ScoopInstaller/Main/master/bucket/7zip.json | jq .version
45+
curl -s https://raw.githubusercontent.com/ScoopInstaller/Main/master/bucket/git.json | jq .version
46+
```
47+
- [ ] Sync PowerShell scripts with upstream if needed (diff with ScoopInstaller/Install)
48+
- [ ] Verify all PAT tokens are valid:
49+
- `WINGET_PAT` - test with `gh auth status`
50+
- `HOMEBREW_UPDATE_TOKEN` - check workflow logs
51+
- [ ] Test installation on all platforms
52+
- [ ] Update dependencies (e.g. Rust, Node, GitHub Actions) as needed
53+
54+
### With Major EIM Changes
55+
56+
- [ ] Update man page with new commands/options
57+
- [ ] Update or create TLDR page
58+
- [ ] Update Docker repository if installation flags changed
59+
- [ ] Update install-esp-idf-action if CLI interface changed
60+
- [ ] Update documentation references
61+
62+
### Quarterly Security Review
63+
64+
- [ ] Check signing certificates expiration dates
65+
- [ ] Rotate PAT tokens approaching expiration
66+
- [ ] Review AWS IAM permissions
67+
- [ ] Check for security advisories on dependencies
68+
- [ ] Update base images (Docker, etc.)
69+
70+
---
71+
72+
## Secrets Reference
73+
74+
| Secret Name | Purpose | Where Used | Renewal Location |
75+
|-------------|---------|------------|------------------|
76+
| `HOMEBREW_UPDATE_TOKEN` | Push to espressif/homebrew-eim | update-homebrew.yml | GitHub PAT settings |
77+
| `WINGET_PAT` | Fork sync and PR creation to WinGet | update-windows-packages.yml | GitHub PAT settings |
78+
| `AWS_ACCESS_KEY_ID` | S3 upload for APT/RPM repos | update-linux-repos.yml | AWS IAM Console |
79+
| `AWS_SECRET_ACCESS_KEY` | S3 upload for APT/RPM repos | update-linux-repos.yml | AWS IAM Console |
80+
| `DL_DISTRIBUTION_ID` | CloudFront cache invalidation | update-linux-repos.yml | AWS CloudFront Console |
81+
| `GITHUB_TOKEN` | Automatic, for release asset uploads | Various workflows | Automatic (no renewal needed) |
82+
83+
### How to Update Secrets
84+
85+
1. Go to repository `Settings > Secrets and variables > Actions`
86+
2. Click on the secret name
87+
3. Click "Update secret"
88+
4. Paste the new value
89+
5. Click "Update secret"
90+
91+
### PAT Token Scopes Required
92+
93+
**HOMEBREW_UPDATE_TOKEN:**
94+
- `repo` (for pushing to homebrew-eim)
95+
96+
**WINGET_PAT:**
97+
- `repo` (for fork access)
98+
- `workflow` (for PR creation)
99+
23100
---
24101

25102
## Overview
@@ -177,6 +254,8 @@ curl -s https://raw.githubusercontent.com/ScoopInstaller/Main/master/bucket/dark
177254
- Python manifests include PEP-514 registry entries for Python discovery by other tools
178255
- Test offline installation after any manifest changes
179256

257+
**Important:** The actual download URLs for the dependency files (7-Zip, Git, Python, etc.) are currently **hardcoded in the offline installer** code. The version update procedure above (fetching from upstream and updating manifests) may therefore not work as described until the installer is changed to resolve or configure those URLs. This is expected to be addressed in [EIM-381](https://jira.espressif.com:8443/browse/EIM-381).
258+
180259
---
181260

182261
## 2. Scoop Installer PowerShell Scripts
@@ -275,6 +354,14 @@ function Install-ScoopOffline {
275354

276355
No workflow in **this** repository builds or updates the Docker image. The image lives in a separate repository (Hahihula/eim-idf-build-docker). Optionally, that repo could be triggered on new EIM releases (e.g. via `repository_dispatch` or a manual trigger); currently it is updated manually when EIM or ESP-IDF versions change.
277356

357+
### Official and reference Docker resources
358+
359+
- **Official Docker image:** The ESP-IDF repository hosts an official Docker image that is being migrated to EIM; this is expected to be in place after the next release.
360+
- **CI images:** CI/build Docker images are maintained in the **esp-dockerfiles** repository.
361+
- **Documentation:** The EIM documentation includes a Dockerfile example; see the [headless usage / Docker integration](https://docs.espressif.com/projects/idf-im-ui/en/latest/headless_usage.html) docs.
362+
363+
The repository and image below are a **proof-of-concept** example for non-interactive EIM installation.
364+
278365
### Repository
279366

280367
**URL:** https://github.com/Hahihula/eim-idf-build-docker
@@ -1039,6 +1126,10 @@ If PRs are not being created:
10391126

10401127
## 11. Scoop Distribution (Online)
10411128

1129+
### Current status
1130+
1131+
**There is no Scoop repository at the moment, and the Scoop-related workflow is currently turned off.** The following section describes how Scoop distribution is intended to work when the workflow is enabled, for future reference.
1132+
10421133
### Used by Workflows
10431134

10441135
**Invocation:** Same as WinGet — the job `update-windows-packages` in `build.yaml` calls `update-windows-packages.yml` with `version: ${{ github.ref_name }}` on release.
@@ -1110,78 +1201,6 @@ eim --version
11101201

11111202
---
11121203

1113-
## Maintenance Checklists
1114-
1115-
### After Each Release
1116-
1117-
- [ ] Verify Homebrew formula updated automatically (check https://github.com/espressif/homebrew-eim)
1118-
- [ ] Verify WinGet PR created (check https://github.com/microsoft/winget-pkgs/pulls)
1119-
- [ ] Verify WinGet PR merged (may take 1-3 days for Microsoft review)
1120-
- [ ] Verify APT repository updated (`apt-cache policy eim`)
1121-
- [ ] Verify RPM repository updated (`dnf info eim`)
1122-
- [ ] Verify Scoop manifests attached to release
1123-
- [ ] Test Docker image with new release
1124-
1125-
### Monthly Maintenance
1126-
1127-
- [ ] Check Scoop manifest template versions against upstream:
1128-
```bash
1129-
curl -s https://raw.githubusercontent.com/ScoopInstaller/Main/master/bucket/7zip.json | jq .version
1130-
curl -s https://raw.githubusercontent.com/ScoopInstaller/Main/master/bucket/git.json | jq .version
1131-
```
1132-
- [ ] Sync PowerShell scripts with upstream if needed (diff with ScoopInstaller/Install)
1133-
- [ ] Verify all PAT tokens are valid:
1134-
- `WINGET_PAT` - test with `gh auth status`
1135-
- `HOMEBREW_UPDATE_TOKEN` - check workflow logs
1136-
- [ ] Test installation on all platforms
1137-
1138-
### With Major EIM Changes
1139-
1140-
- [ ] Update man page with new commands/options
1141-
- [ ] Update or create TLDR page
1142-
- [ ] Update Docker repository if installation flags changed
1143-
- [ ] Update install-esp-idf-action if CLI interface changed
1144-
- [ ] Update documentation references
1145-
1146-
### Quarterly Security Review
1147-
1148-
- [ ] Rotate PAT tokens approaching expiration
1149-
- [ ] Review AWS IAM permissions
1150-
- [ ] Check for security advisories on dependencies
1151-
- [ ] Update base images (Docker, etc.)
1152-
1153-
---
1154-
1155-
## Secrets Reference
1156-
1157-
| Secret Name | Purpose | Where Used | Renewal Location |
1158-
|-------------|---------|------------|------------------|
1159-
| `HOMEBREW_UPDATE_TOKEN` | Push to espressif/homebrew-eim | update-homebrew.yml | GitHub PAT settings |
1160-
| `WINGET_PAT` | Fork sync and PR creation to WinGet | update-windows-packages.yml | GitHub PAT settings |
1161-
| `AWS_ACCESS_KEY_ID` | S3 upload for APT/RPM repos | update-linux-repos.yml | AWS IAM Console |
1162-
| `AWS_SECRET_ACCESS_KEY` | S3 upload for APT/RPM repos | update-linux-repos.yml | AWS IAM Console |
1163-
| `DL_DISTRIBUTION_ID` | CloudFront cache invalidation | update-linux-repos.yml | AWS CloudFront Console |
1164-
| `GITHUB_TOKEN` | Automatic, for release asset uploads | Various workflows | Automatic (no renewal needed) |
1165-
1166-
### How to Update Secrets
1167-
1168-
1. Go to repository `Settings > Secrets and variables > Actions`
1169-
2. Click on the secret name
1170-
3. Click "Update secret"
1171-
4. Paste the new value
1172-
5. Click "Update secret"
1173-
1174-
### PAT Token Scopes Required
1175-
1176-
**HOMEBREW_UPDATE_TOKEN:**
1177-
- `repo` (for pushing to homebrew-eim)
1178-
1179-
**WINGET_PAT:**
1180-
- `repo` (for fork access)
1181-
- `workflow` (for PR creation)
1182-
1183-
---
1184-
11851204
## External Links Reference
11861205

11871206
| Component | Repository/URL |

0 commit comments

Comments
 (0)