OAI / OAI/tools.openapis.org

refactor: Migrate Gulp build to GitHub Actions

Open
#289 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
177
Forks
87
Avg merge
1m
Merged PRs (30d)
1

Description

Proposal: Remove Gulp from the data build

Gulp currently orchestrates the pipeline that produces src/_data/tools.yaml (gulpfile.js/index.js), piping content through lib/data/transform/* functions via gulp-transform/gulp-rename. Since GitHub Actions already schedules and runs this build, Gulp's task-runner/stream layer adds indirection without adding capability.

Finding: every lib/data/transform/* function is already Gulp-agnostic — each is a plain (content) => string | Promise<string> function, confirmed by their existing unit tests, which call them directly with a single string argument. None of them use Gulp's Vinyl file argument, and all GitHub API auth (GH_API_USERNAME/GH_API_TOKEN/GH_API_CONCURRENCY_LIMIT) is already read from process.env inside the transform functions, not injected by Gulp. So this is purely an orchestration swap — no changes to lib/data/** logic.

Approach:

  • Replace gulpfile.js/index.js with scripts/build-data.js, a plain Node script (--task full|metadata) that chains the same lib/data functions in the same order, using the same yargs flags (--metadata, --env-file, --output-dir, --dry-run) and dotenv loading as today.
  • Move the non-Gulp-specific config (gulpfile.js/metadata.json, gulpfile.js/.env) to config/metadata.json / config/.env.
  • Update package.json's build:data:full/build:data:metadata scripts to call the new script; drop the gulp, gulp-cli, gulp-rename, gulp-transform dependencies.
  • No GitHub Actions workflow changes neededfull.yaml/metadata.yaml invoke the build only via yarn run build:data:full/build:data:metadata, so preserving those script names means the workflows keep working unchanged.
  • Verify equivalence once during PR review by diffing old-Gulp vs new-script output (tools.yaml, raw-sources.yaml) under --dry-run; no new automated test needed since the underlying lib/data/transform/* logic (and its existing test coverage) is untouched.
  • Update README.md, CONTRIBUTING.md, and CLAUDE.md references to Gulp accordingly.

Single PR, low risk — mechanical orchestration swap only.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with gulpfile.js/index.js, the existing lib/data/transform/* unit tests, and the build:data:full and build:data:metadata scripts in package.json. Trace the current task order and flags before creating scripts/build-data.js and moving the configuration files. Done means the scripts produce equivalent tools.yaml and raw-sources.yaml output under --dry-run, Gulp dependencies and references are removed, and the existing GitHub Actions commands still work.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, javascript, node.js
Domain
build-system, documentation, tooling
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.