95 lines
2.7 KiB
Markdown
95 lines
2.7 KiB
Markdown
# Contributing to this package
|
|
|
|
## Table of Contents
|
|
|
|
- [Contributing to this package](#contributing-to-this-package)
|
|
- [Table of Contents](#table-of-contents)
|
|
- [Version and CHANGELOG updates](#version-and-changelog-updates)
|
|
- [Version](#version)
|
|
- [CHANGELOG](#changelog)
|
|
- [Style](#style)
|
|
- [Example](#example)
|
|
- [Updating a CHANGELOG that has a NEXT](#updating-a-changelog-that-has-a-next)
|
|
|
|
## Version and CHANGELOG updates
|
|
|
|
### Version
|
|
|
|
Any change that needs to be published in order to take effect must update the version in pubspec.yaml. There are very few exceptions:
|
|
|
|
- PRs that only affect tests.
|
|
- PRs that only affect example apps.
|
|
- PRs that only affect local development (e.g., changes to ignored lints).
|
|
- PRs that only make symbolic changes to the docs (e.g. typo).
|
|
|
|
And the new version must follow the [pub versioning philosophy].
|
|
|
|
### CHANGELOG
|
|
|
|
All version changes must have an accompanying CHANGELOG update. Even version-exempt changes should usually update CHANGELOG by adding a special `NEXT` entry at the top of `CHANGELOG.md` (unless they only affect development of the package, such as test-only changes):
|
|
|
|
```md
|
|
## NEXT
|
|
|
|
* Description of the change.
|
|
|
|
## 1.0.2
|
|
...
|
|
```
|
|
|
|
This policy exists because some changes (e.g., updates to examples) that do not need to be published may still be of interest to clients of a package.
|
|
|
|
#### Style
|
|
|
|
For consistency, all CHANGELOG entries should follow a common style:
|
|
|
|
- Use `##` for the version line. A version line should have a blank line before and after it.
|
|
- Use `-` for individual items.
|
|
- Entries should use present tense indicative for verbs, with "this version" as an implied subject. For example, "Adds cool new feature.", not "Add" or "Added".
|
|
- Entries should end with a `.`.
|
|
- Breaking changes should be introduced with **BREAKING CHANGE**:, or **BREAKING CHANGES**: if there is a sub-list of changes.
|
|
|
|
#### Example
|
|
|
|
```md
|
|
## 2.0.0
|
|
|
|
- Adds the ability to fetch data from the future.
|
|
- **BREAKING CHANGES**:
|
|
- Removes the deprecated `neverCallThis` method.
|
|
- URLs parameters are now `Uri`s rather than `String`s.
|
|
|
|
## 1.0.3
|
|
|
|
- Fixes a crash when the device teleports during a network operation.
|
|
```
|
|
|
|
#### Updating a CHANGELOG that has a NEXT
|
|
|
|
If you are adding a version change to a CHANGELOG that starts with `NEXT`, and your change also doesn't require a version update, just add a description to the existing `NEXT` list:
|
|
|
|
```md
|
|
## NEXT
|
|
|
|
* Description of your new change.
|
|
* Existing entry.
|
|
|
|
## 1.0.2
|
|
...
|
|
```
|
|
|
|
If your change does require a version change, do the same, but then replace `NEXT` with the new version. For example:
|
|
|
|
```md
|
|
## 1.0.3
|
|
|
|
* Description of your new change.
|
|
* Existing entry.
|
|
|
|
## 1.0.2
|
|
...
|
|
```
|
|
|
|
<!-- Links -->
|
|
[pub versioning philosophy]: https://dart.dev/tools/pub/versioning
|