Issues & Pull Requests
Titles
Describe outputs, not implementation: An issue or PR title should describe the desired end result, not the implementation. The exception is child issues/subissues of an epic. Be specific about the domain. Poozle operates a monorepo, so being specific about what is being changed in the PR or issue title is important.
good issue title: Building the Poozle Typescript IDK should not build unrelated packages. Describes desired end state and the intent is understandable without reading the full issue.
subpar PR title: Update tests. Which tests? What was the update?
good PR title: Integration Github: supports get-collection API. Specific about the domain and change that was made.
Pull Request Title Convention
When creating a pull request follow the naming conventions depending on the change being made.
In general the pull request title starts with an emoji with the integration you’re doing the changes, eg (✨ Integration Github: add new model Users).
Poozle uses this pattern to automatically assign team reviews and build the product release notes.
| Pull Request Type | Emoji | Examples |
|---|---|---|
| New Integration | 🎉 | 🎉 New Integration: Github |
| Add a feature to an existing integration | ✨ | ✨ Integration Github: add new model Users |
| Fix a bug | 🐛 | 🐛 Integration Github: fix start date parameter in spec |
| Documentation (updates or new entries) | 📝 | 📝 Fix Github integration changelog |
| It’s a breaking change | 🚨 | 🚨🚨🐛 Integration Github: fix a complex bug |
Any refactors, cleanups, etc.. that are not visible improvements to the user should not have emojis.
If you’re code change is doing more than one change type at once we strongly recommend to break into multiple pull requests. It helps us to review and merge your contribution.
Descriptions
Context: Provide enough information (or a link to enough information) in the description so team members with no context can understand what the issue or PR is trying to accomplish. This usually means you should include two things:
-
Some background information motivating the problem
-
A description of the problem itself
-
Good places to start reading and file changes that can be skipped
Some examples:
insufficient context: Create an OpenAPI to JSON schema generator. Unclear what the value or problem being solved here is.
good context:
When creating or updating integrations, we spend a lot of time manually transcribing JSON Schema files based on OpenAPI docs. This is necessary because OpenAPI and JSON schema are very similar but not perfectly compatible. This process is automatable. Therefore we should create a program which converts from OpenAPI to JSONSchema format.