From e22db67a76d408d893de278c4737b7abc8be0748 Mon Sep 17 00:00:00 2001 From: magicDGS Date: Sun, 25 Jun 2023 16:42:28 +0200 Subject: [PATCH] Add Contributing to README --- CONTRIBUTING.md | 2 +- README.md | 26 ++++++++++++++++++++++++-- 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 47513d2..4147c96 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,6 +32,6 @@ If you contribute to _ygoprodeck-openapi_ significantly (e.g., with a Pull Reque Currently we do not have any major contributor to the project. Be the first! -[code_of_conduct]: https://github.com/magicDGS-gaming/ygoprodeck-openapi/blob/master/CODE_OF_CONDUCT.md +[code_of_conduct]: https://github.com/magicDGS-gaming/ygoprodeck-openapi/blob/main/CODE_OF_CONDUCT.md [issue_tracker]: https://github.com/magicDGS-gaming/ygoprodeck-openapi/issues [pull_requests]: https://github.com/magicDGS-gaming/ygoprodeck-openapi/pulls diff --git a/README.md b/README.md index 968fd30..263ab8f 100644 --- a/README.md +++ b/README.md @@ -18,22 +18,42 @@ We aim to provide a documentation-as-code describing the API to allow developers _Note that as a third-party project without affiliation to the [YGOPRODeck API] the interoperability might be broken. We rely on your help to keep it in sync through pull-requests and/or issues._ +## Contributing + +Please read [CONTRIBUTING.md](https://github.com/magicDGS-gaming/ygoprodeck-api/blob/main/CONTRIBUTING.md). +for details on our code of conduct, and the process for collaborating on the project. + +### Bug reports + +Before submitting a new bug report, please search for keywords in our [Issue Tracker][issue_tracker]. +If you cannot find your problem, fill in a new [issue][issue_tracker]. + ## Getting started +### Pre-requisites + +The project only requires `npm` to be installed, relying on the `npx` command to run redocly and portman. + +We recommend to use an IDE with support for OpenAPI to edit the YAML files. + +Postman can also be used to open both artifacts (OpenAPI and postman collection). + +## Build & Test + To build and test the description and postman collection run `make`. This will create the following artifacts: * `dist/ygoprodeck-api.yaml` - bundled OpenAPI YAML * `dist/ygoprodeck.postman.json` - postman collection JSON -### Build +### Bundle only To bundle the API into a single file, run `make build`. This script also performs the validation and if the definition is not valid it won't create the bundle. To create the postman collection without tests, run `make postman-collection` -### Test +### Test only To only run the tests with newman, run `make test` (as it is run with portman, the postman collection would be also created). This requires that a build for the bubdled OpenAPI description is alredy in place. @@ -46,3 +66,5 @@ The [YGOPRODeck API] is not affiliated with this project and it is provided as a [YGOPRODeck]: https://ygoprodeck.com/ [YGOPRODeck API]: https://ygoprodeck.com/api-guide/ +[issue_tracker]: https://github.com/magicDGS-gaming/ygoprodeck-openapi/issues +[pull_requests]: https://github.com/magicDGS-gaming/ygoprodeck-openapi/pulls \ No newline at end of file