Skip to content

Latest commit

 

History

History
93 lines (64 loc) · 8.17 KB

CONTRIBUTING.md

File metadata and controls

93 lines (64 loc) · 8.17 KB
Raw

Contributing

SPS Commerce is committed to providing and maintaining the documentation and rulesets provided in this repository. This serves as foundational details for alignment of the internal and external REST APIs built at SPS Commerce. Community engagement from both external organizational partners or additional external consumers of these API Standards is encouraged, though SPS Commerce reserves the right to make and accept updates that are in the best interest of their API Platform first and foremost.

Opening issues is the best method to drive feature requests, bug fixes, discussions or thoughts you have about the repository contents and roadmap. SPS Commerce is determined to continually evolve the standards and rulesets with more content as driven internally by our technical organization and API consumers.

Note: we have a code of conduct, please follow it in all your interactions with this project.

Development

Updating

If you have a a simple and obvious addition, such as a grammar or documentation fix, or even a new proposed ruleset, providing a Pull Request from your forked repository is the best method to engage the community with further discussion and review. If you are proposing larger scale changes or potential change in direction for the API Standards, it would be best to first open an issue first before you begin any work to avoid any wasted time.

When updating content, consider:

  • "MUST", "MUST NOT", "SHOULD" and "SHOULD NOT" are used in the context as defined in RFC2119.
  • Provide links to other parts of the standards where associations need to be made but at all costs reduce duplication as it is detrimental to maintenance and accuracy.
  • Clearly call out any assumptions inline.
  • Ambiguity is clarified through examples.
  • Examples of what not to do are just as important as what to do.
  • All examples should use standardized consistency and syntax for schema definitions.
  • No differences between internal or external APIs should be called out, as all APIs should be crafted in preparation for externalization.
  • Compose and reuse other API Guidelines, standards and schemas where possible including the use of existing industry standard RFCs.
  • Usage of American English (en-US) is desirable for documentation consistency.
  • Create Spectral rules, where possible, for any new API Standards added to documentation.
  • New Spectral rule codes should always be prefixed with sps to indicate they come from this library and ruleset.
  • Link Spectral rule codes to the API Standards documentation markdown following the existing pattern with the checkmark icon:
<a name="sps-your-rule" href="#sps-your-rule"><i class="fa fa-check-circle" title="#sps-your-rule"></i></a>

Newly suggested API Standards will be evaluated based on the Design Principles.

Testing

All Spectral rules added MUST be unit-tested with positive and negative examples demonstrating when the rule results in linting error/warning and then also succeeding. Jest is used to create tests using a custom spectral harness abstracted from the spectral-core npm packages. A minimum version of node.js 16 is required.

Each Spectral rule is placed in its own test file, in the proper designated directory defined by its documentation category. The file name convention is sps-{your-rule-code}.test.js.

For simplicity, jest should be installed globally (at version 28.1.1 at time of writing, see updated version in package.json). Tests should be executed from the rulesets directory.

# install jest global
/> npm install -g [email protected]

# navigate inside the rulesets directory
/> cd rulesets

# install all dependencies
/rulesets> npm install

# run all tests
/rulesets> jest

# run a specific test based on spectral code / file
/rulesets> jest -t sps-hosts-https-only

You can also manually execute any ruleset.yml spectral file against the root.openapi.yml testing reference for manual sandboxing:

# install spectral globally for CLI usage
/rulesets> npm install -g @stoplight/spectral-cli

# execute linting (note the directory is "rulesets")
/rulesets> spectral lint test/root.openapi.yml --ruleset src/url-structure.ruleset.yml

For more information on how Spectral is consumed and used refer to OpenAPI Linting with Spectral.

Pull Requests

Pull requests can be submitted for any updates or bug fixes from forked versions of the repository. CODEOWNERS file automatically ensures your pull request is assigned to a maintainer that will review and respond in a reasonable period of time. When submitting your Pull Request, be sure to:

  • Add enough details via the Pull Request description about what your update and change is doing.
  • Update any relevant documentation with the change being made in the same Pull Request.
  • Update unit tests for any associated ruleset or documentation modifications.

Pull request validation via GitHub Actions will be approved after the Pull Request is reviewed to ensure no modifications to the GitHub Actions workflow. This is necessary on every Pull Request from community contributors regardless of previous history.

Merging & Releasing

Updates are only added via Pull Requests, and they will be merged by a maintainer (indicated in CODEOWNERS) at the appropriate time. The maintainer will always use a squash merge and apply a GIT Commit message for the squash adhering to the Semantic Release format that will calculate the SemVer value based on syntax of the message. The message will indicate if it is a patch, major or minor change. Further discussion on how semantic versioning is used in these standards should be reviewed.

When pushed to the main branch and versioned, a consolidated file of all the Spectral rulesets and a zip file of all the markdown documentation is made available as a GitHub Release immediately, which identifies the changes made in that release along with the version number. Documentation is made available via GitHub Pages automatically shortly after at: [https://spscommerce.github.io/sps-api-standards]. The consolidated Spectral ruleset is also made available in the main branch at the root so it can be referenced via Raw GitHub content: [https://raw.githubusercontent.com/SPSCommerce/sps-api-standards/main/sps-api-standards.spectral.yml]

During a pull request review, maintainers are responsible for:

  • Validating that no-changes occur within the .github root folder of the repository, which could contain modifications to the release workflow in any way. Public fork pull request workflows from GitHub Actions can be approved only after validated.
  • Additional pull requests from the same external contributors MUST be re-reviewed and approved on every commit, regardless of prior contribution history.
  • Elevating malicious, ill-intent or any behavior violating the Code of Conduct to the SPS Security team.
  • Evaluating the changes for their positive impact for the internal SPS Commerce applications and the external community of users.
  • Ensuring that all reasonably possible test automation is contributed in the same pull request as the modification themselves.
  • Providing clear and timely feedback on next steps if not closed.