Skip to content

Latest commit

 

History

History
124 lines (83 loc) · 5.25 KB

CONTRIBUTING.md

File metadata and controls

124 lines (83 loc) · 5.25 KB
Raw

Contributing

First things first: thank you for contributing to this project. The following is a set of contribution guidelines. Reading and following these guidelines will help us make the contribution process easy and effective for everyone involved. You can contribute to the project by creating or reviewing pull requests, suggesting new features, or by reporting bugs. All of this is greatly appreciated and required to create and maintain great API Guidelines.

Skip to:

Create a pull request

Changes and additions to the API Guidelines require a pull request against main. This ensures that the intended changes

  • can be properly reviewed with context.
  • do not negatively affect or block the build process.
  • integrate into the overall picture.

In any case, choose a descriptive PR title that explains the context and main purpose of the PR. Use the present tense and start the title description with a verb.

We adhere to conventional commits to describe the structure of a commit message. If your commit type is feat or fix, refer to Compose a changelog relevant pull request.

Create a pull request draft

If your changes are not yet ready for review but you would still like to create a pull request to better organize your work, create a pull request draft.

Compose a changelog relevant pull request

Changelog entries are generated by using the pull request title and commit body. The following conventional commit types are used to generate the changelog entries:

  • feat - used for new rules
  • fix - used for updates and bug fixes

For a consistent appearance of the changelog and to help you with the changelog entries, there is a template in the pull request body to use and edit:

Changelog:

### New

- Rule name [New ruleID](relative path)
- [Name of new section](relative path)


### Update

- Refactored rule "rule name [ruleID](relative path)".
- Relaxed criteria in rule "rule name [ruleID](relative path)".

### Removal

The rule "rule name" has been removed, because...
(if applicable) It has been replaced by rule "rule name [ruleID](relative path)".

Pay attention to the following when editing this template:

  • Use the Changelog: marker to separate any additional information for reviewers to understand your actions and to optionally reference related issues.
  • Remove anything from the template that is not relevant for your entry.
  • You can use the GitHub Markdown preview to see what the changelog entry will look like.
  • The PR body can include a mixture of changes, but the PR title always requires either a feat or fix entry.

Here's an example pull request:

fix(contract): rework contract description
Fixes issue #08015

Changelog:

### Update

- Refactored rule "MUST provide meaningful `source` context attribute [R200010](../api-guidelines/async/format/cloudevents/rules/must-provide-meaningful-source-context-attribute.md)".
- Updated the information on contract for [async](https://api.otto.de/portal/guidelines/event-guidelines/contract) and [rest](https://api.otto.de/portal/guidelines/rest-guidelines/contract).

Review a pull request (checklist)

  • Does the added/changed information belong where it is placed?
  • Does the change introduce security vulnerabilities, sensitive data, or internal information?
  • Is the wording used correctly and consistently, and does it fit into the overall concept?
  • Does the pull request comply with the conventional commits spec and does the commit message convey the purpose of the change, see also Compose a changelog relevant pull request?
  • Will this change highly impact the way we design APIs, and should this be discussed amongst API providers/API community?

Add a new guideline

You are welcome to propose a new API guideline. Each API guideline requires a unique rule ID, which must be noted in the front matter of the file. A rule ID consists of an "R" followed by 6 digits, for example, R200023. To identify an unused and thus available rule ID, run the following command:

grep -r "^id: R" api-guidelines | rev | cut -d" " -f1 | rev | sort | less

You can choose any rule ID that is not included in the list.

Report a bug

Nobody is perfect. If you find a bug, we appreciate a bug report via a GitHub issue. Bug reports help us improve. Include as many details as possible to help us understand the issue.

Suggest a feature

You're welcome to report a feature or suggest an improvement to an existing functionality via a GitHub issue. Include as many details as possible to help us understand the requirement.