Skip to content

Commit c4a7874

Browse files
author
Konrad Jamrozik
authored
Improve docs: README.md and CONTRIBUTING.md (#289)
1 parent edd69b1 commit c4a7874

File tree

3 files changed

+166
-69
lines changed

3 files changed

+166
-69
lines changed

‎.markdownlint.jsonc

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
{
2+
// This repository is markdownlint-enabled.
3+
// Website: https://github.com/DavidAnson/markdownlint
4+
// VS Code extension: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
5+
//
6+
// The implicit, default set of rules is defined in:
7+
// https://github.com/DavidAnson/markdownlint/blob/v0.30.0/doc/Rules.md
8+
9+
// MD013 - Line length
10+
// https://github.com/DavidAnson/markdownlint/blob/main/doc/md013.md
11+
//
12+
// "line_length" : 120:
13+
// Allow lines of length 120 instead of the default 80. Keep in sync with guide lines .vscode/settings.json.
14+
//
15+
// "tables": false
16+
// Do not include tables. Breaking a line in a table to meet the line length would add a line break in the table
17+
// itself. We do not want that.
18+
//
19+
// "headings": false
20+
// Do not include headings. One cannot break lines in headings, and we sometimes need long ones, e.g. for FAQs.
21+
"MD013": { "line_length" : 120, "tables": false, "headings": false },
22+
23+
// MD025 - Multiple top-level headings in the same document
24+
// https://github.com/DavidAnson/markdownlint/blob/main/doc/md025.md
25+
//
26+
// We like multiple top-headings.
27+
"MD025": false,
28+
29+
// MD034 - Inline HTML
30+
// https://github.com/DavidAnson/markdownlint/blob/main/doc/md033.md
31+
//
32+
// Forbid using inline HTML elements except <br/>. We use <br/> within tables.
33+
"MD033": { "allowed_elements": ["br"]}
34+
}

‎CONTRIBUTING.md

+101-33
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,129 @@
11
# Contributing
22

3-
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
3+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
4+
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact
5+
[[email protected]](mailto:[email protected]) with any additional questions or comments.
6+
7+
## Table of contents
8+
9+
* [Prerequisites](#prerequisites)
10+
* [Build the code](#build-the-code)
11+
* [Troubleshoot](#troubleshoot)
12+
* [Run `oad` locally from sources](#run-oad-locally-from-sources)
13+
* [Install `oad` globally from sources or npm feed](#install-oad-globally-from-sources-or-npm-feed)
14+
* [Uninstall `oad` globally](#uninstall-oad-globally)
15+
* [Purge the obsolete `oad` package from your system](#purge-the-obsolete-oad-package-from-your-system)
16+
17+
<!-- <small><i><a href='http://ecotrust-canada.github.io/markdown-toc/'>
18+
Table of contents generated with markdown-toc</a></i></small> -->
419

520
## Prerequisites
621

7-
- [Node.js](https://nodejs.org/) (14.x or higher)
8-
- [.NET runtime and SDK](https://aka.ms/dotnet-download)
9-
- [.NET CLI tools](https://github.com/dotnet/cli/releases) version 2.0.0 or higher
22+
To execute any instructions in this file, first ensure you fulfill all the following prerequisites:
1023

11-
## Build scripts
24+
1. Install [Node.js](https://nodejs.org/), version 14.x or higher.
25+
1. Install [.NET runtime and SDK](https://aka.ms/dotnet-download), version 6 or higher.
26+
1. Install [.NET CLI tools](https://github.com/dotnet/cli/releases) version 2.0.0 or higher.
27+
1. Execute all commands in this file from your [`openapi-diff`] git repo local clone root dir.
28+
1. Run `npm install` to install the required node modules.
1229

13-
Run `npm install` to install the required modules.
30+
## Build the code
1431

15-
```sh
16-
npm install
17-
```
32+
`openapi-diff` is composed both of TypeScript and .NET/C# projects, all of which have to be built
33+
to be able to run the tool locally from sources.
1834

19-
## How to build the C# code
35+
The core logic for `openapi-diff` is written in C# and compiled to a .NET binary.
36+
The CLI for `openapi-diff` is written in TypeScript and compiled to a Node.js binary.
2037

21-
The core logic for openapi-diff is written in C# and compiled to a .NET binary.
38+
| Build command | Effect |
39+
|-|-|
40+
| `npm run dn.build` | Runs [`dotnet build`] and related commands to build the C# code. |
41+
| `npm run tsc` | Builds the TypeScript code. |
2242

23-
Use `dn.build` npm script to build the C# code.
43+
For more commands, see the [`package.json`](/package.json) `scripts` element.
44+
Notably:
2445

25-
```sh
26-
npm run dn.build
27-
```
46+
| Command | Effect |
47+
|-|-|
48+
| `npm run dn.restore` | Runs [`dotnet restore`] in preparation to build the C# code. |
49+
| `npm run dn.test` | Runs [`dotnet test`] and related commands to test the C# code. |
2850

29-
## How to test the C# code
51+
### Troubleshoot
3052

31-
To run all tests under the repo
53+
If the `npm run dn.build` command outputs error like:
3254

33-
```sh
34-
npm run dn.test
35-
```
55+
> C:\Program Files\dotnet\sdk\8.0.100\Sdks\Microsoft.NET.Sdk\targets\Microsoft.PackageDependencyResolution.targe
56+
ts(266,5): error NETSDK1005: Assets file 'C:\(...)\openapi-diff\src\core\OpenApiDiff\ob
57+
j\project.assets.json' doesn't have a target for 'netcoreapp6.0'. Ensure that restore has run and that you have
58+
included 'netcoreapp6.0' in the TargetFrameworks for your project.
59+
60+
Then first run `npm run dn.restore` and then run the `npm run dn.build` command again.
3661

37-
## How to build the TypeScript code
62+
## Run `oad` locally from sources
3863

39-
The CLI for openapi-diff is written in TypeScript and compiled to a Node.js binary.
64+
After you have built the C# and TypeScript code, you can run the `openapi-diff` aka `oad` tool locally.
4065

41-
Use `tsc` npm script to build the TypeScript code.
66+
1. Run [`npm link`] once.
67+
2. Then you can use `oad` by running `oad -h`.
68+
69+
> [!CAUTION]
70+
> Following commands have different behavior: `oad`, `oad -h`, `oad --help`.
71+
> As of 11/2/2023 only `oad -h` appears to work as intended.
72+
73+
## Install `oad` globally from sources or npm feed
74+
75+
You can also install the `oad` tool globally and run it from anywhere.
4276

4377
```sh
44-
npm run tsc
78+
npm list -g @azure/oad # verify oad is not installed globally
79+
npm install -g # Install oad from local repo clone source
80+
npm list -g @azure/oad # verify oad is installed
81+
oad --version # verify correct version got installed.
82+
oad -h
4583
```
4684

47-
## How to run locally
85+
> [!CAUTION]
86+
> Be careful to use `@azure/oad` and not `oad` as the latter is an obsolete, deprecated package.
87+
<!-- markdownlint-disable MD028 -->
88+
<!-- Disabling warning about empty line inside blockquote -->
89+
> [!TIP]
90+
> If you want to install `oad` not from your local sources, but the latest from the npm feed,
91+
> use this alternative `npm install`:
92+
> `npm install -g @azure/oad`
4893
49-
After you have built the C# and TypeScript code, you can run the openapi-diff tool locally.
50-
To run the openapi-diff tool locally, use the `npm run start` command.
94+
### Uninstall `oad` globally
5195

52-
```sh
53-
node dist/cli.js --help
96+
To uninstall `oad` globally:
97+
98+
``` sh
99+
# if installed from sources
100+
npm uninstall -g
101+
# if installed from npm feed
102+
npm uninstall -g @azure/oad
54103
```
55104

56-
You can also install the package globally and run it from anywhere.
105+
## Purge the obsolete `oad` package from your system
57106

58-
```sh
59-
npm install -g
60-
oad --help
107+
To purge the obsolete, deprecated `oad` package from your system, including [the cache].
108+
109+
``` sh
110+
# To remove oad from the cache
111+
npm cache ls oad
112+
npm cache clean <copy paste here entries from "ls oad"> # run once per each entry from "ls oad"
113+
npm cache verify # to fix the cache after removing oad
114+
115+
# To remove oad from the local node_modules
116+
npm uninstall oad
117+
npm list oad # Should denote no packages installed
118+
119+
# To remove oad from the global node_modules
120+
npm uninstall -g oad
121+
npm list -g oad # Should denote no packages installed
61122
```
123+
124+
[`openapi-diff`]: https://github.com/Azure/openapi-diff
125+
[`dotnet restore`]: https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-restore
126+
[`dotnet build`]: https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-build
127+
[`dotnet test`]: https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-test
128+
[`npm link`]: https://docs.npmjs.com/cli/v10/commands/npm-link
129+
[the cache]: https://docs.npmjs.com/cli/v10/configuring-npm/folders#cache

‎README.md

+31-36
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,31 @@
1-
[![Build Status](https://dev.azure.com/azure-sdk/public/_apis/build/status/public.openapi-diff?branchName=master)](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=135&branchName=master)
2-
3-
# How to install
4-
5-
```javascript
6-
npm install -g @azure/oad
7-
```
8-
9-
# Usage
10-
11-
```bash
12-
vishrut@visshamac openapi-diff $ oad compare --help
13-
Commands:
14-
compare <old-spec> <new-spec> Compares old and new open api specification for
15-
breaking changes.
16-
17-
Options:
18-
--version Show version number [boolean]
19-
-l, --logLevel Set the logging level for console.
20-
[choices: "off", "json", "error", "warn", "info", "verbose", "debug", "silly"]
21-
[default: "warn"]
22-
-f, --logFilepath Set the log file path. It must be an absolute filepath. By
23-
default the logs will stored in a timestamp based log file
24-
at "/Users/vishrut/oad_output".
25-
-j, --inJson A boolean flag indicating whether output format of the
26-
messages is json. [boolean] [default: true]
27-
-h, --help Show help [boolean]
28-
-o, --oldTagName The tag name for the old specification file. If included it
29-
indicates that the old spec file is a readme file
30-
-n, --newTagName The tag name for the new specification file. If included it
31-
indicates that the new spec file is a readme file
32-
```
33-
34-
# Contributing
35-
36-
See [CONTRIBUTING.md](./CONTRIBUTING.md)
1+
# About openapi-diff
2+
3+
[![Build Status][build status]][build pipeline]
4+
5+
This repository contains source code of `openapi-diff` aka `oad` aka "Breaking change detector tool" npm package.
6+
This package is invoked internally by the [azure-rest-api-specs] and [azure-rest-api-specs-pr] repos
7+
`Swagger Breaking Change` and `Breaking Change(Cross-Version)` GitHub checks, validating PRs submitted to them.
8+
9+
For description of the overall process of which `oad` is part of, see https://aka.ms/azsdk/specreview.
10+
11+
[build status]: https://dev.azure.com/azure-sdk/public/_apis/build/status/public.openapi-diff?branchName=main
12+
[build pipeline]: https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=135&branchName=main
13+
[azure-rest-api-specs]: https://github.com/Azure/azure-rest-api-specs
14+
[azure-rest-api-specs-pr]: https://github.com/Azure/azure-rest-api-specs-pr
15+
16+
## npm package
17+
18+
- [@azure/oad] ![npm package version shield](https://img.shields.io/npm/v/@azure/oad)
19+
- [package.json]
20+
21+
> [!CAUTION]
22+
> Do not use the package [oad] ![npm package version shield](https://img.shields.io/npm/v/oad). It is deprecated and obsolete.
23+
24+
[@azure/oad]: https://www.npmjs.com/package/@azure/oad
25+
[package.json]: /package.json
26+
[oad]: https://www.npmjs.com/package/oad
27+
28+
## How to run locally
29+
30+
See relevant section in [CONTRIBUTING.md](./CONTRIBUTING.md)
31+

0 commit comments

Comments
 (0)