Skip to content

Latest commit

 

History

History
172 lines (131 loc) · 8.91 KB

CONTRIBUTING.md

File metadata and controls

172 lines (131 loc) · 8.91 KB
Raw

Contributing

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Table of contents

Table of contents generated with yzhang.markdown-all-in-one

Prerequisites

To execute any instructions in this file, first ensure you fulfill all the following prerequisites:

  1. Install Node.js, version 14.x or higher.
  2. Install .NET runtime and SDK, version 6 or higher.
  3. Install .NET CLI tools version 2.0.0 or higher.
  4. Execute all commands in this file from your openapi-diff git repo local clone root dir.
  5. Run npm ci to install the required node modules.

Build the code

openapi-diff is composed both of TypeScript and .NET/C# projects, all of which have to be built to be able to run the tool locally from sources.

The core logic for openapi-diff is written in C# and compiled to a .NET binary.
The CLI for openapi-diff is written in TypeScript and compiled to a Node.js binary.

Build command Effect
npm run dn.build Runs dotnet build and related commands to build the C# code.
npm run tsc Builds the TypeScript code.

For more commands, see the package.json scripts element. Notably:

Command Effect
npm run dn.restore Runs dotnet restore in preparation to build the C# code.
npm run dn.test Runs dotnet test and related commands to test the C# code.

Troubleshoot

If the npm run dn.build command outputs error like:

C:\Program Files\dotnet\sdk\8.0.100\Sdks\Microsoft.NET.Sdk\targets\Microsoft.PackageDependencyResolution.targe ts(266,5): error NETSDK1005: Assets file 'C:(...)\openapi-diff\src\core\OpenApiDiff\ob j\project.assets.json' doesn't have a target for 'netcoreapp6.0'. Ensure that restore has run and that you have included 'netcoreapp6.0' in the TargetFrameworks for your project.

Then first run npm run dn.restore and then run the npm run dn.build command again.

Run oad locally from sources

After you have built the C# and TypeScript code, you can run the openapi-diff aka oad tool locally.

  1. Run npm link once.
  2. Then you can use oad by running oad -h.

Caution

Following commands have different behavior: oad, oad -h, oad --help. As of 11/2/2023 only oad -h appears to work as intended.

Reproduce specs PR CI failure of Swagger BreakingChange or BreakingChange(Cross-Version)

If Swagger BreakingChange or BreakingChange(Cross-Version) checks fail on your Azure/azure-rest-api-specs[-pr] PR, you can reproduce the failure locally as follows:

  • Open the GitHub check pane.
  • Click the hyperlinked View Azure DevOps build log for more details. Open the relevant job (BreakingChange or CrossVersionBreakingChange) and a task within the job with the same name. Search for log ENTER definition runOad. This log will show you the oldSpec and newSpec values, which you can pass as input to oad when running it locally, per Run oad locally from sources. Note you will have to clone locally relevant git branches with the specs.

Install oad globally from sources or npm feed

You can also install the oad tool globally and run it from anywhere.

npm list -g @azure/oad # verify oad is not installed globally
npm install -g # Install oad from local repo clone source
npm list -g @azure/oad # verify oad is installed 
oad --version # verify correct version got installed.
oad -h

Caution

Be careful to use @azure/oad and not oad as the latter is an obsolete, deprecated package.

Tip

If you want to install oad not from your local sources, but the latest from the npm feed, use this alternative npm install:
npm install -g @azure/oad

Uninstall oad globally

To uninstall oad globally:

# if installed from sources
npm uninstall -g 
# if installed from npm feed
npm uninstall -g @azure/oad

Purge the obsolete oad package from your system

To purge the obsolete, deprecated oad package from your system, including the cache.

# To remove oad from the cache
npm cache ls oad 
npm cache clean <copy paste here entries from "ls oad"> # run once per each entry from "ls oad"
npm cache verify # to fix the cache after removing oad

# To remove oad from the local node_modules
npm uninstall oad
npm list oad # Should denote no packages installed

# To remove oad from the global node_modules
npm uninstall -g oad
npm list -g oad # Should denote no packages installed

Publish the package

  • Ensure you bumped the package version in openapi-diff package.json.
  • Queue a run of the openapi-diff pipeline and approve the publish stage. (Note: there is also the public.openapi-diff pipeline for CI checks.)
  • Verify in @azure/oad versions that the newest package version was published on npmjs.org. You can also run npm show @azure/oad.
  • Save it to openapi-platform feed via upstream feeds of openapi-platform.
    • For the desired version, you must click Save to feed in the context menu of the hidden triple-dot button on the right. It will reveal on hover.
    • You may need to wait a bit until the newest version shows up in the Upstream Versions tab.
  • To make openapi-alps use the newly published package:
    • Ensure that you update the minimum package version in relevant package.json files and then run rush update and commit the changes.
    • ❗ Do the update even if semver rules say the new package version is in scope. E.g. if the version is ~0.10.7 but you published 0.10.8, then still update the entry to ~0.10.8.
    • If you will not modify any package.json at all, rush will not recognize the newly published package version. This can be worked around by running rush update --full, but this is discouraged.
    • Example file: private/azure-swagger-validation/azureSwaggerValidation/package.json.
    • Example openapi-alps PR doing the package update: #537791.
  • Redeploy relevant openapi-alps parts to pick up the new package, even if you didn't had to commit any changes. Follow this doc.