Update package documentation by mit-mit · Pull Request #605 · flutter/website

mit-mit · 2017-06-16T13:39:23Z

sethladd

overall comment: I think we need to work on the taxonomy and its usefulness to our users. I think we can simplify the taxonomy.

sethladd · 2017-06-16T16:30:08Z

+
+## Package introduction
+
+Dart packages enable the creation of modular code that can easily be shared. A


Should we just say "Packages ..." instead of "Dart packages" ?

I would keep "Dart packages" here.

Yes, I will keep it. There are also java, swift, etc. packages that a plugin developer will be familiar with.

sethladd · 2017-06-16T16:32:31Z

+  [AngularDart](https://webdev.dartlang.org/angular) and Flutter. A concrete
+  example is the [`path`](https://pub.dartlang.org/packages/path) package.
+
+* *Flutter packages*: General packages which contain Flutter specific


I'm not sure we want to make this distinction. The kind of package is the same: a pub package.

I think the user cares about one thing:

where do I go to see all the packages I can use as a Flutter developer

The differences you talk about here are implementation details that probably don't matter. Only: "will it work with Flutter?"

See above, agree consumers don't care. Producers need to care (and this is in developing-packages.md)

sethladd · 2017-06-16T16:33:00Z

+  their use to Flutter only. A concrete example is the
+  [`fluro`](https://pub.dartlang.org/packages/fluro) package.
+
+* *Flutter plugins*: Flutter packages which in additional to the Dart code also


I think the package/plugin distinction probably isn't too helpful. A plugin isn't a sub-type of package.

maybe some packages offer plugins, but it's still a package.

sethladd · 2017-06-16T16:35:24Z

+
+### Package types {#types}
+
+Flutter supports several kinds of packages:


Maybe the framing is better as : "there are two kinds of code you can put into a Flutter package: dart code, and native code. If you are writing Dart code that has a dependency on Flutter, do this: ...."

(instead of "different kinds of packages", let's use "packages can contain different kinds of code")

I totally agree for package consumers. But you re commenting on 'developing-packages.md'; I don't see how we can avoid knowledge of the differences for producers.

Look at 'using-packages.md', I just talk about packages there.

Whoops, sorry this was meant as a reply to your "overall taxanomy" comment up top

as a package developer, it's still one kind of package. It can contain a few different things: dart library, native code, examples, LICENSE, etc. But it's one package format.

The details you talk about are important, I'm commenting on the phrasing. s/types of packages/kinds of things inside a package

Please don't call it "native" code. There's nothing more native about Java than Dart on Android, they both compile down to machine code, and neither are what the kernel is written in.

Landed on a compromise: There are Dart packages and Plugin packages. We do need this distinction for authors as the steps for developing one are very different. We do not need the distinction for consumers as the API of both types (and all packages in general) is Dart.

sethladd · 2017-06-16T16:36:06Z

+
+## Developing packages
+
+### Create a package project


You use "-ing" in many titles, but you use "Create" here. Maybe "Creating..." is more consistent

also, do we mean "project" ? I think that's superfluous. "Creating a package" works.

Good point, removed

sethladd · 2017-06-16T16:44:45Z

+   * From the terminal: Run `flutter packages get`
+   * From IntelliJ: Click 'Packages Get' in the action ribbon at the top of `pubspec.yaml`
+
+1. Build or run your app. As part of this, Flutter will add the package code to


This is a little confusing. The code was already added to my add when I installed ("get") the package.

I'm not sure we need this last bullet. Only two steps! :)

maybe, Step Three is "import the package's library into your app"

sethladd · 2017-06-16T16:45:55Z

+in IntelliJ). This will retrive the highest available version of the package,
+which is allowed by the version constraint you have specified in `pubspec.yaml`.
+
+### Dependencies on unpublished packages


This seems generic and duplicates existing docs. Should we just link to somewhere?

I couldn't find a short set of existing docs for this, so given the important of understanding decided a bit of duplication was OK. I do link to the Pub versioning guide for complete details.

sethladd · 2017-06-16T16:46:31Z

+
+## Examples
+
+### Example: Using the CSS Colors package {#css-example}


You say "CSS Colors package" and then you start talking about URL Launcher. Is that intentional?

Oh, my bad, left over from an older version of this

sethladd · 2017-06-16T16:46:49Z

+
+1. Run `flutter packages get` in the terminal, or click 'Packages get' in IntelliJ
+
+1. Open `lib/main.dart` and replace its full contents with:


BTW great example!!!

sethladd · 2017-06-16T16:47:46Z

+The [URL Launcher](https://pub.dartlang.org/packages/url_launcher) plugin
+enables you to open the default browser on the mobile platform to display a
+given URL. It demonstrates how packages may also contain platform-specific code
+(we call these packages 'plugins'). It is supported on both Android and iOS.


It doesn't seem like there's any difference between installing and using a package, or a package+plugin.

If there is no difference, do we need this example?

I think this helps deliver that very message; if you are a consumer there is no difference.

sethladd · 2017-06-16T16:48:54Z

Thank you very much for working on this!!

mit-mit · 2017-06-22T13:15:49Z

Thanks for all the great feedback! Uploaded a v2, please take a look.

…ages

sethladd · 2017-06-22T15:30:42Z

+
+### Package types {#types}
+
+Flutter supports several kinds of packages:


I think we're being confusing here. There is one type of package: a pub package (or, call it a Dart package). It can contain many different kinds of things: Dart code, plugin code, or a combination.

I agree that package developers might want to know the different kinds of things they can put in it.

If you're willing to change this phrasing to something like:

Flutter uses pub for its package format and distribution.

A pub (Dart) package can contain many things: Dart code, plugin code, example code, assets, and more.

Maybe it's as simple as "Dart packages can contain several kinds of code: Dart, plugin"

So, it's not about supporting different kinds of packages, it's that there are different kinds of contents.

I don't see the confusion; actually, I find what you are suggesting more confusing, and over-abstracted.

To use an analogy, the term "xml file" is commonly used rather than the more generic "text file containing text in xml format". It's just convenient to use more concrete terms.

sethladd · 2017-06-22T15:31:28Z

+To test the package, add [unit tests](https://flutter.io/testing/#unit-testing)
+in a `test` directory.
+
+## Developing plugin packages {#plugin}


Then this would become "Developing packages with plugins"

sethladd

LGTM but I think we have a much clearer definitions if we talk about a single type of package: Dart/pub, and the various contents/components inside the package.

Putting a plugin into a package doesn't change the type of the package. It's still a pub package.

mit-mit · 2017-06-26T13:21:45Z

Yes, a plugin package is still a Dart package; in fact, it's a specialization of a Dart package. Made that clearer.

mit-mit · 2017-06-26T18:30:28Z

TravisCI failures:

- ./_site/developing-packages/index.html
  *  External link https://github.com/flutter/website/blob/master/developing-packages.md failed: 404 No error
- ./_site/using-packages/index.html
  *  External link https://github.com/flutter/website/blob/master/using-packages.md failed: 404 No error

These are the auto-inserted links for the 'Edit Source' action -- those fail, as these new pages are not on GitHub yet, as the PR hasn't merged yet. Will have to update the Rakefile to skip these.

Skip links that have been auto-inserted for the 'Edit Source' action

Add wildcard

Fix RegExp

mit-mit added 2 commits June 16, 2017 15:34

Update plugin docs to also talk about packages

0717d90

Replace old content with redirect

f950dee

googlebot added the cla: yes Contributor has signed the Contributor License Agreement label Jun 16, 2017

mit-mit requested a review from sethladd June 16, 2017 13:39

sethladd reviewed Jun 16, 2017

View reviewed changes

Review feedback from Seth

d7e18d4

mit-mit added 3 commits June 22, 2017 15:33

A few simplifications

abf3393

Fix broken links

624c15a

Merge branch 'master' of https://github.com/flutter/website into pack…

df7b7f9

…ages

sethladd reviewed Jun 22, 2017

View reviewed changes

sethladd approved these changes Jun 22, 2017

View reviewed changes

mit-mit added 2 commits June 26, 2017 15:24

Clarify what a plugin package + fix a few typos

985024e

Fix formating of pubspecs

97e0ec5

mit-mit added 3 commits June 26, 2017 20:36

Update Rakefile

1e1b872

Skip links that have been auto-inserted for the 'Edit Source' action

Update Rakefile

d5a4591

Add wildcard

Update Rakefile

8d77a6f

Fix RegExp

mit-mit merged commit 963b9bc into flutter:master Jun 27, 2017

mit-mit deleted the packages branch June 27, 2017 14:41


		## Package introduction

		Dart packages enable the creation of modular code that can easily be shared. A


		### Package types {#types}

		Flutter supports several kinds of packages:


		## Examples

		### Example: Using the CSS Colors package {#css-example}


		1. Run `flutter packages get` in the terminal, or click 'Packages get' in IntelliJ

		1. Open `lib/main.dart` and replace its full contents with:

Conversation

mit-mit commented Jun 16, 2017

Uh oh!

sethladd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mit-mit Jun 22, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sethladd commented Jun 16, 2017

Uh oh!

mit-mit commented Jun 22, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sethladd left a comment

Choose a reason for hiding this comment

Uh oh!

mit-mit commented Jun 26, 2017

Uh oh!

mit-mit commented Jun 26, 2017

Uh oh!

Reviewers

Assignees

Labels

mit-mit Jun 22, 2017 •

edited

Loading