dart_lsc 0.0.2+1

  • Readme
  • Changelog
  • Installing
  • 44

Dart LSC #

A tool for shepherding changes through the Dart ecosystem.

Usage #

Each LSC starts with a piece of code that can modify a given package. This piece of code is the Migration. A Migration has a fairly simple interface, with just 2 core methods, one method determines if a package need to be changed. And applies the change to a given package.

abstract class Migration {
  Future<IsChangeNeededResult> isChangeNeeded(Directory packageDir, String dependencyName, String options);

  Future<MigrationResult> migrate(Directory packageDir, String dependencyName, String options);
}

An example Migration is MigrateTo1 which implements a common migration: When package foo is ready to bump it's version from 0.1.2 to 1.0.0 MigrateTo1 updates packages that depend on foo to set a friendly version constraint of foo: ">0.1.2 <=2.0.0". Some more details on why this is useful to do.

Get a GitHub command line auth token #

The dart_lsc tool tracks the migration status on GitHub and sends PRs on your behalf. To grant the tool the permission to act on your behalf we need to provide it with a GitHub auth token, to generate a token follow the steps in "Creating a personal access token for the command line".

For the example we'll assume that the GITHUB_TOKEN environment variable is set with the token.

Initialize the migration #

We initialize a migration with the following command:

dart_lsc\
  initialize\
  --dependent_packages_of=foo\
  --github_auth_token=${GITHUB_TOKEN}\
  --tracking_repository_owner=<owner>\
  --tracking_repository=<tracking_repository>\
  --title="Prepare for foo 1.0.0"

The dart_lsc tool will:

  1. Query pub.dev for all the packages that depend on package foo.
  2. Create a new project in the <tracking_repository>.
  3. File a tracking issue in the <tracking_repository> for each package that depend on foo.

When the project is initialized dart_lsc prints:

LSC project has been succesfully initialized!
Project URL: https://github.com/<owner>/<tracking_repository>/projects/1

This is what the initialized project looked like when I created an LSC for the battery plugin:

The LSC project #

LSC are tracked in a GitHub project, with columns that represent what each package is waiting for. The dart_lsc tool automates the entirety of the migration for each package, when something unexpected happens the issue is moved to the "Need Manual Intervention" column, issues in this column are the only ones that require human attention.

The update_script #

The Migration code mentioned above needs is wrapped by a command line tool that follows a specific protocol. We refer to this tool as the update_script and the one we have for MigrateTo1 is called migrate_to_1.

Stepping through the LSC #

The dart_lsc tool provides a step command, which goes over all the issues filed during migration initialization when possible pushes the migration through one more step (e.g by sending a PR or marking a package as migrated).

This step command should be executed periodically until the migration is complete.

dart_lsc step\
 --tracking_repository_owner=<tracking_repository_owner>\
 --tracking_repository=<tracking_repository>\
 --project=1\
  --github_auth_token=${GITHUB_TOKEN}\
 --dependent_packages_of=foo\
 --update_script="migrate_to_1"\
 --update_script_options={\"foo\":\"0.1.2\"}\
 --title="Adjust foo's version constraints to accept the 1.0.0 version [dart_lsc]"\
 --pr_body="This should be a safe change, for more details see: https://github.com/flutter/flutter/wiki/Package-migration-to-1.0.0\n\nThis change was auto generated by [dart_lsc](https://github.com/amirh/dart_lsc)."

The dart_lsc tool will send PRs and update issues on your behalf. When PRs are merged or commented on the tool updates their issues appropriately. Run this command in a day or two to keep moving this migration forward.

Remember that dart_lsc automates most of the workflow, if something required human attention it will be moved to the "Needs Manual Intervention" column that's where you should be looking after running a step.

Record your LSC #

If you're using dart_lsc for a migration please list your migration in this tracking document.

0.0.2+1 #

  • Fix a bug with not converting an iterable to a list.

0.0.2 #

  • Delete fork after package migration is complete.
  • Add a --dry_run flag.
  • Improve heuristics for finding a package on GitHub.
  • Allow updating packages without a CHANGELOG.md file.

0.0.1 #

  • Initial version.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  dart_lsc: ^0.0.2+1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:dart_lsc/executable.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
0
Health:
Code health derived from static analysis. [more]
94
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
80
Overall:
Weighted score of the above. [more]
44
Learn more about scoring.

We analyzed this package on May 30, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.2
  • pana: 0.13.8-dev

Health issues and suggestions

Document public APIs. (-1 points)

2 out of 2 API elements have no dartdoc comment.Providing good documentation for libraries, classes, functions, and other API elements improves code readability and helps developers find and use your API.

Fix lib/src/github.dart. (-2.96 points)

Analysis of lib/src/github.dart reported 6 hints, including:

line 201 col 12: Don't explicitly initialize variables to null.

line 279 col 9: The value of the local variable 'issueNumber' isn't used.

line 280 col 12: The value of the local variable 'url' isn't used.

line 299 col 29: This function has a return type of 'Future<List

line 304 col 18: The value of the local variable 'query' isn't used.

Fix lib/src/git_repository.dart. (-1 points)

Analysis of lib/src/git_repository.dart reported 2 hints:

line 5 col 8: Unused import: 'package:path/path.dart'.

line 7 col 8: Unused import: 'global.dart'.

Fix lib/src/step_command.dart. (-1 points)

Analysis of lib/src/step_command.dart reported 2 hints:

line 58 col 17: This function has a return type of 'FutureOr

line 173 col 5: Future results in async function bodies must be awaited or marked unawaited using package:pedantic.

Fix additional 6 files with analysis or formatting issues.

Additional issues in the following files:

  • lib/executable.dart (Run dartfmt to format lib/executable.dart.)
  • lib/src/base_command.dart (Run dartfmt to format lib/src/base_command.dart.)
  • lib/src/dependents_fetcher.dart (Run dartfmt to format lib/src/dependents_fetcher.dart.)
  • lib/src/initialize_command.dart (Run dartfmt to format lib/src/initialize_command.dart.)
  • lib/src/pub_package.dart (Run dartfmt to format lib/src/pub_package.dart.)
  • lib/src/version_bump.dart (Run dartfmt to format lib/src/version_bump.dart.)

Maintenance suggestions

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package.

Common filename patterns include main.dart, example.dart, and dart_lsc.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.

Package is pre-v0.1 release. (-10 points)

While nothing is inherently wrong with versions of 0.0.*, it might mean that the author is still experimenting with the general direction of the API.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.7.0 <3.0.0
args ^1.5.3 1.6.0
file ^5.1.0 5.1.0
http ^0.12.0+4 0.12.1
meta ^1.1.8 1.1.8
path ^1.6.4 1.7.0
pub_semver ^1.4.3 1.4.4
pubspec_parse ^0.1.5 0.1.5
Transitive dependencies
charcode 1.1.3
checked_yaml 1.0.2
collection 1.14.12
http_parser 3.1.4
intl 0.16.1
json_annotation 3.0.1
source_span 1.7.0
string_scanner 1.0.5
term_glyph 1.1.0
typed_data 1.1.6
yaml 2.2.1
Dev dependencies
pedantic ^1.8.0 1.9.0
test ^1.6.0