Repository navigation
Maintainability Roadmap #308
Description
A potential roadmap to improve maintainability, ending with the archiving of this repo.
TypeScript
- Update
SwaggerBreakingChangesinopenapi-alpsto callnpm exec --no oadinstead of@azure/oad@~0.10.6 - Move code to
azure-rest-api-specsrepo, foldereng/tools/openapi-diff - Align deps and config with
typespec-validation, add toeng/package.json - Upgrade all dependencies to latest
- If some are really difficult we can choose to stay back, but anything older than latest is a liability
- Remove .NET code from package, replace with call to nuget/dotnet to install and run separate .NET package
- Existing CLI name
oadseems good and short, and aligns withtsv- But could rename cli to
openapi-diffto be more descriptive
- But could rename cli to
- Deprecate npm package
@azure/oad
.NET
- Move code to
azure-sdk-toolsrepo, foldertools/openapi-diff - Rename to
Azure.Sdk.Tools.OpenApiDiff - Align deps and config from a similar existing tool, perhaps
http-fault-injector - Publish nuget package and/or dotnet tool to devops nuget feed (similar to
http-fault-injector) - Could potentially move code to
azure-rest-api-specs, and compile dynamically- But it would be the first .NET code in the repo
- It would add a dependency on .NET SDK (rather than just .NET runtime)
Docs
- Move docs to
azure-rest-api-specsrepo
Final
- Archive this repo (
Azure/openapi-diff)
Reacted by Konrad Jamrozik and Timothee Guerin
Metadata
Metadata
Assignees
Labels
No labels
Type
Projects
- Status
Activity
[-]Roadmap to 1.0.0[/-][+]Roadmap[/+][-]Roadmap[/-][+]Maintainability Roadmap[/+]konrad-jamrozik commentedon Mar 21, 2024
Disclaimer: I do not have strong opinions on that and I am OK with the proposed approach.
Re:
I guess we decided on the mono-repo model? I do like the standalone repo model for better inner loop development, decoupling and versioning experience.
Why? Shouldn't openapi-diff have only the deps it needs? What if typespec-validation has a dep that openapi-diff doesn't need?
I think we could rethink the name as it leads to confusion with
oavandaov(akaazure-openapi-validator) andLintDiff(due todiff)Case in my point above:
LintDiffis a separate tool unrelated tooad. Related code inopenapi-alpscallingoadisbreaking-change.tsandreakingChangeRuleManager.tsThe code in
openapi-diffconceptually belongs together. It doesn't really sit well with me to split it into two parts and shelve them inside two bigger mono-repos. If we would have use cases where we reuse these two parts independently of each other then it would make more sense to me.mikeharder commentedon Mar 21, 2024
What I meant here was to align the deps and config, not actually copy. I mean things like align the versions of common dependencies like
typescriptwhere we try to stay consistent within a given monorepo.IMO the main question here is what do you want devs to use on the command-line? We chose
tsvfor "typespec-validation" since we thought a short name similar totspwould be easiest for devs to use. If the command is mostly used in scripts, or we just want to eliminate confusion, then a long name likeopenapi-diffis fine with me.Sorry I meant "SwaggerBreakingChange" here.
In my experience, optimizing for ease of maintenance:
If a tool is only used in one repo, put the tool in the repo itself, and build/install the tool as part of "installing the repo toolset". This is how
typespec-validationandtypespec-requirementwork inazure-rest-api-specs, and they are a breeze to maintain.If a tool is used in multiple repos, or it's written in a "foreign" language and you don't want to add that language's toolset to your repo, put it in a monorepo and share via packages.