dart-package-maintenance

Name: dart-package-maintenance
Author: kevmoo

225installs16forks

How to install dart-package-maintenance?

kevmoo/dash_skills/dart-package-maintenance

$npx -y skills add kevmoo/dash_skills --skill dart-package-maintenance

Installs into the current project.

Summary

Guidelines for maintaining external Dart packages, covering versioning, publishing workflows, and pull request management. Use when updating Dart packages, preparing for a release, or managing collaborative changes in a repository.

Files · 1

View on GitHub

SKILL.md

1	# Dart Package Maintenance
2
3	Guidelines for maintaining Dart packages in alignment with Dart team best
4	practices.
5
6	## Discovery
7
8	To find maintenance tasks or inconsistencies:
9
10	### Consistency Checks
11	Ensure the latest version in `CHANGELOG.md` matches `pubspec.yaml`:
12	- Compare the top header in `CHANGELOG.md` with the `version:` field in
13	`pubspec.yaml`.
14
15	## Versioning
16
17	### Semantic Versioning
18	- Major: Breaking changes.
19	- Minor: New features (non-breaking API changes).
20	- Patch: Bug fixes, documentation, or non-impacting changes.
21	- Unstable packages: Use `0.major.minor+patch`.
22	- Recommendation: Aim for `1.0.0` as soon as the package is stable.
23
24	### Pre-Edit Verification
25	- Check Published Versions: Before modifying `CHANGELOG.md` or
26	`pubspec.yaml`, ALWAYS check the currently released version (e.g., via
27	`git tag` or `pub.dev`).
28	- Do Not Amend Released Versions: Never add new entries to a version header
29	that corresponds to a released tag.
30	- Increment for New Changes: If the current version in `pubspec.yaml`
31	matches a released tag, increment the version (e.g., usually to `-wip`) and
32	create a new section in `CHANGELOG.md`.
33
34	- Consistency: The `CHANGELOG.md` header must match the new
35	`pubspec.yaml` version.
36
37	- SemVer Guidelines:
38	- Breaking Changes: Bump Major, reset Minor/Patch
39	(e.g., `2.0.0-wip`, `0.5.0-wip`).
40	- New Features: Bump Minor, reset Patch
41	(e.g., `1.1.0-wip`, `0.4.5-wip`).
42	- Bug Fixes: Bump Patch (e.g., `1.0.1-wip`).
43
44	### Changelog Content
45	- Focus on User Impact: Entries in `CHANGELOG.md` should focus on changes
46	visible to or impacting the end-user (e.g., new features, bug fixes,
47	breaking changes).
48	- Omit Internal Changes: Do not include internal refactorings, test
49	changes, or other modifications that do not affect the package's behavior
50	or API for the user.
51
52	### Work-in-Progress (WIP) Versions
53	- Immediately after a publish, or on the first change after a publish, update
54	`pubspec.yaml` and `CHANGELOG.md` with a `-wip` suffix (e.g., `1.1.0-wip`).
55	- This indicates the current state is not yet published.
56
57	### Breaking Changes
58	- Evaluate the impact on dependent packages and internal projects.
59	- Consider running changes through internal presubmits if possible.
60	- Prefer incremental rollouts (e.g., new behavior as opt-in) to minimize
61	downstream breakage.
62
63	## Publishing Process
64
65	1. Preparation: Remove the `-wip` suffix from `pubspec.yaml` and
66	`CHANGELOG.md` in a dedicated pull request.
67	2. Execution: Run `dart pub publish` (or `flutter pub publish`) and resolve
68	all warnings and errors.
69	3. Tagging: Create and push a git tag for the published version:
70	- For single-package repos: `v1.2.3`
71	- For monorepos: `package_name-v1.2.3`
72	- Example: `git tag v1.2.3 && git push --tags`
73
74	## Pull Request Management
75
76	- Commits: Each PR should generally correspond to a single squashed commit
77	upon merging.
78	- Shared History: Once a PR is open, avoid force pushing to the branch.
79	- Conflict Resolution: Prefer merging `main` into the PR branch rather than
80	rebasing to resolve conflicts. This preserves the review history and comments.
81	- Reviewing: Add comments from the "Files changed" view to batch them.
82	- Local Inspection: Use `gh pr checkout <number>` to inspect changes
83	locally in your IDE.

People who liked this also viewed

6 picks

Type

dart-package-maintenance

225installs16forks

View on GitHub

How to install dart-package-maintenance?

kevmoo/dash_skills/dart-package-maintenance

$npx -y skills add kevmoo/dash_skills --skill dart-package-maintenance

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Dart Package Maintenance
2
3	Guidelines for maintaining Dart packages in alignment with Dart team best
4	practices.
5
6	## Discovery
7
8	To find maintenance tasks or inconsistencies:
9
10	### Consistency Checks
11	Ensure the latest version in `CHANGELOG.md` matches `pubspec.yaml`:
12	- Compare the top header in `CHANGELOG.md` with the `version:` field in
13	`pubspec.yaml`.
14
15	## Versioning
16
17	### Semantic Versioning
18	- Major: Breaking changes.
19	- Minor: New features (non-breaking API changes).
20	- Patch: Bug fixes, documentation, or non-impacting changes.
21	- Unstable packages: Use `0.major.minor+patch`.
22	- Recommendation: Aim for `1.0.0` as soon as the package is stable.
23
24	### Pre-Edit Verification
25	- Check Published Versions: Before modifying `CHANGELOG.md` or
26	`pubspec.yaml`, ALWAYS check the currently released version (e.g., via
27	`git tag` or `pub.dev`).
28	- Do Not Amend Released Versions: Never add new entries to a version header
29	that corresponds to a released tag.
30	- Increment for New Changes: If the current version in `pubspec.yaml`
31	matches a released tag, increment the version (e.g., usually to `-wip`) and
32	create a new section in `CHANGELOG.md`.
33
34	- Consistency: The `CHANGELOG.md` header must match the new
35	`pubspec.yaml` version.
36
37	- SemVer Guidelines:
38	- Breaking Changes: Bump Major, reset Minor/Patch
39	(e.g., `2.0.0-wip`, `0.5.0-wip`).
40	- New Features: Bump Minor, reset Patch
41	(e.g., `1.1.0-wip`, `0.4.5-wip`).
42	- Bug Fixes: Bump Patch (e.g., `1.0.1-wip`).
43
44	### Changelog Content
45	- Focus on User Impact: Entries in `CHANGELOG.md` should focus on changes
46	visible to or impacting the end-user (e.g., new features, bug fixes,
47	breaking changes).
48	- Omit Internal Changes: Do not include internal refactorings, test
49	changes, or other modifications that do not affect the package's behavior
50	or API for the user.
51
52	### Work-in-Progress (WIP) Versions
53	- Immediately after a publish, or on the first change after a publish, update
54	`pubspec.yaml` and `CHANGELOG.md` with a `-wip` suffix (e.g., `1.1.0-wip`).
55	- This indicates the current state is not yet published.
56
57	### Breaking Changes
58	- Evaluate the impact on dependent packages and internal projects.
59	- Consider running changes through internal presubmits if possible.
60	- Prefer incremental rollouts (e.g., new behavior as opt-in) to minimize
61	downstream breakage.
62
63	## Publishing Process
64
65	1. Preparation: Remove the `-wip` suffix from `pubspec.yaml` and
66	`CHANGELOG.md` in a dedicated pull request.
67	2. Execution: Run `dart pub publish` (or `flutter pub publish`) and resolve
68	all warnings and errors.
69	3. Tagging: Create and push a git tag for the published version:
70	- For single-package repos: `v1.2.3`
71	- For monorepos: `package_name-v1.2.3`
72	- Example: `git tag v1.2.3 && git push --tags`
73
74	## Pull Request Management
75
76	- Commits: Each PR should generally correspond to a single squashed commit
77	upon merging.
78	- Shared History: Once a PR is open, avoid force pushing to the branch.
79	- Conflict Resolution: Prefer merging `main` into the PR branch rather than
80	rebasing to resolve conflicts. This preserves the review history and comments.
81	- Reviewing: Add comments from the "Files changed" view to batch them.
82	- Local Inspection: Use `gh pr checkout <number>` to inspect changes
83	locally in your IDE.

People who liked this also viewed

6 picks

Type