This file provides general guidance for anyone contributing to IBM Cloud Node.js SDK projects produced by the IBM OpenAPI SDK Generator.
If you are having problems using the APIs or have a question about IBM Cloud services, please ask a question on dW Answers or Stack Overflow.
This SDK project follows a coding style based on the Airbnb conventions.
This repository uses tslint for linting the TypeScript code and eslint for linting the JavaScript test files.
The rules for each are defined in tslint.json and test/.eslintrc.js, respectively.
It is recommended that you do not change these files, since the automatically generated code complies with the defined rules.
You can run the linter with the following commands. Replacing “check” with “fix” will cause the linter to automatically fix any linting errors that it can.
npm run tslint:checknpm run eslint:check
Commit messages should follow the Angular Commit Message Guidelines. This is because our release tool - semantic-release - uses this format for determining release versions and generating changelogs. Tools such as commitizen or commitlint can be used to help contributors and enforce commit messages. Here are some examples of acceptable commit messages, along with the release type that would be done based on the commit message:
| Commit message | Release type |
|---|---|
fix(example service): fix integration test to use correct credentials |
Patch Release |
feat(global catalog): add global-catalog service to project |
|
feat(global search): re-gen service code with new v3 API definitionBREAKING CHANGE: The global-search service has been updated to reflect version 3 of the API. |
If you want to contribute to the repository, follow these steps:
- Fork the repo.
- Install dependencies:
npm install - Build the code:
npm run build - Verify the build before beginning your changes:
npm run test-unit - Develop and test your code changes.
- Commit your changes. Remember to follow the correct commit message guidelines.
- Push to your fork and submit a pull request to the main branch.
- Be sure to sign the CLA.
This section will guide you through the steps to generate the Node.js code for a service and add the generated code to your SDK project.
- Validate the API definition - before trying to process the API definition with the SDK generator, we strongly recommend that you validate the API definition with the IBM OpenAPI Validator . Example:
lint-openapi -s example-service.yaml
This command will display a list of errors and warnings found in the API definition as well as a summary at the end. It's not required that you fix all errors and warnings before trying to use the SDK generator, but this step should identify any critical errors that will need to be fixed prior to the generation step.
- Next, run the SDK generator to process your API definition and generate the service and unit test code for the service.
You'll find instructions on how to install and run the SDK generator on the generator repository wiki.
Set the output location for the generated files to be the root directory of the project.
Here is an example of how to generate the Node.js code for an API definition.
Suppose your API definition file is named my-service.json and contains the definition of the "My Service"
service.
To generate the code into your project, run these commands:
cd <project-root>
openapi-sdkgen.sh generate -g ibm-node -i my-service.json -o .
The generated service code is placed in a source directory named after the service
(my-service for this example) under the project root.
You should have one source directory per service.
The unit test code is placed in test/unit with a filename that reflects the service
(my-service.v1.test.js for this example).
Hint: you can generate an initial integration test for your service by including the --genITs option
when running the SDK generator. This will generate an integration test in the test/integration directory.
It is expected that the generated integration test is a starting point which will need manual editing to form
an effective integration test for the service.
-
Update the service table in the
README.mdfile to add an entry for the new service. -
Update
.gitignoreto add an entry for your service to theservice-specific tsc outputs, like this:
# service-specific tsc outputs (js files)
my-service/*.js
This will ensure that the typescript build outputs are not inadvertently committed to the git repository.
- Repeat the steps in this section for each service to be included in your project.
Out of the box, npm run test runs linting, unit tests, and integration tests (which require credentials).
To run only the unit tests (sufficient for most cases), use npm run test-unit.
To run all of the project's integration tests, you can run npm run test-integration.
Note that in order to run all of an SDK project's integration tests, you'll need to first make sure
that the required credentials files (one per service) are present and located in the project's root directory.
To run only a specific test, pass the file name to jest, like this example:
jest test/integration/example-service.v1.test.js
Note: if you do not yet have jest installed locally, you can run npm i -g jest to install it.
See the jest documentation for all the options you can use to further configure jest.
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
(b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or
(c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
(d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.