diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4f0c2e1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,89 @@ +# Contributing guide + +This guide will ensure that you have all the necessary information needed to be an effective contributor to Openapi-forge + +We are actively looking for contributors to help increase the Forge's capabilities and robustness + +
+ +## Before you create an issue + +- Does the issue already exist? _Remember to check the **open** and **closed** tickets_ + +
+ +## What to include in the issue + +- ### Bug + + - A short and clear title of the bug + - Forge version (and generator versions if it relates to the generators) + - Reproduction steps or a link to a project that shows the bug + - Expected and actual behaviour

+ +- ### New Feature / Improvement + - A short and clear title of the new feature / improvement + - A more detailed description of the new feature / improvement (adding code snippets if you desire)

+ +## Before you start working on an issue + +- Fork the repos you will need to work on. _You may also need the generators_ +- Have you contributed before? _If not, look for issues with the 'good first issue' label_ +- Is it assigned to anyone else? _If so, post a message to see if the assignee is still working on it_ +- Is it assigned to you? _If not, post a message stating your intent so that the maintainers and other contributors know what is being developed_ +- Do you understand the issue fully? _If not, ask on in the issue. We are all here to help you contribute_ + +
+ +## Before you submit a PR + +- Link issue that PR addresses +- Link any related PRs _This could happen when forge and generator needs updating_ +- Have you added tests? +- Are all workflow steps passing? +- Is it ready for review? _If not, create a draft_ + +
+ +## Testing + +You can test openapi-forge on all of the language generators from one command: + +``` +% openapi-forge help test-generators +Usage: openapi-forge test-generators [options] + +Test language specific generators. + +Options: + -g, --generators Narrow down the generators to test. Each letter is a generator, combine letters to test multiple generators, options are: + c (CSharp), t (TypeScript) (default: "ct") + -c, --csharp Sets the location of the CSharp generator. Default is a directory called 'openapi-forge-csharp' in the same location as + openapi-forge (default: "../../openapi-forge-csharp") + -t, --typescript Sets the location of the TypeScript generator. Default is a directory called 'openapi-forge-typescript' in the same + location as openapi-forge (default: "../../openapi-forge-typescript") + -l, --logLevel Sets the logging level, options are: quiet ('quiet', 'q' or '0'), standard (default) ('standard', 's' or '1'), verbose + ('verbose', 'v' or '2') (default: "1") + -h, --help display help for command +``` + +If the testing doesn't work you may be using the wrong script-shell configuration in npm. To keep scripts working in both Unix and Windows machines the shell expected in the project is git-bash. To change your shell type you can run the command below, changing the file location if you have your git-bash executable in a different location: + +``` +npm config set script-shell "C:\\Program Files\\Git\\bin\\bash.exe" +``` + +
+ +## Points to remember when contributing + +- This project uses [semantic-release](https://semantic-release.gitbook.io/semantic-release/) which enforces [Angular Commit Message Conventions](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-format). Ensure you are writing your commit messages correctly. Husky hooks have got your back for ensuring correct format but will not prevent the use of wrong types. +- The NPM scripts below can help you fix failing workflow steps: + +``` + npm run test:generators + npm run format:check + npm run format:write + npm run lint:check + npm run lint:write +``` diff --git a/README.md b/README.md index abac559..660a7c8 100644 --- a/README.md +++ b/README.md @@ -109,8 +109,6 @@ Options: If a URL is given than it assumes that you are giving it a git repository. Otherwise it searches for a local generator folder and finally if no local generator is found it looks for an npm package and installs it if it does not exist. -TODO: Elaborate - ## Developer guide The following is a very high-level overview of the generation process: @@ -120,22 +118,3 @@ The following is a very high-level overview of the generation process: - generate - the generators are implemented using the [Handlebars templating engine](https://handlebarsjs.com/). TODO: Elaborate etc ... - -## Testing - -You can test openapi-forge on all of the language generators from one command: - -``` -% openapi-forge help test-generators -Usage: openapi-forge test-generators [options] - -Test language specific generators. - -Options: - -g, --generators Narrow down the generators to test. Each letter is a generator, combine letters to test multiple generators, options are: c (CSharp), t (TypeScript) (default: "ct") - -c, --csharp Sets the location of the CSharp generator. Default is a directory named 'openapi-forge-csharp' in the same location as openapi-forge (default: "./openapi-forge-csharp") - -t, --typescript Sets the location of the TypeScript generator. Default is a directory named 'openapi-forge-typescript' in the same location as openapi-forge (default: "./openapi-forge-typescript") - -l, --logLevel Sets the logging level, options are: quiet ('quiet', 'q' or '0'), standard (default) ('standard', 's' or '1'), verbose ('verbose', 'v' or '2') (default: "1") - -o, --outputFile [file] Writes the testing results to a JSON file, defaults to "test-results.json" - -h, --help display help for command -```