opensource.google.com

Menu

Docs

Dart

go/thirdpartydart

This describes Dart-specific guidance for checking code into //piper/third_party/dart.

IMPORTANT: Read go/thirdparty first. For Dart-specific questions, email emailremoved@.

General policies

Preserving licenses

Third-party licenses must be preserved on generated code. There are several build rules to support Dart in google3. The dart_application rule compiles Dart to JavaScript. This rule automatically includes the text of any LICENSE file included in its (or its dependencies’) srcs lists in the resulting JavaScript.

Adding a new version of an existing package

We strongly prefer having a single version of each package in google3, but sometimes changes are a bit more complex. Similar to other languages, we allow creating a new directory with the new version of a package, and separately updating all projects to use the new package. More details are available at our policies and layout conventions design document.

Do not approve CLs unless you are the last third-party-* reviewer

When multiple reviewers are auto-assigned to a brand-new //piper/third_party package, only the last reviewer to LGTM should ‘g4 approve’ the CL. Other reviewers should LGTM and then defer to the remaining auto-assigned reviewers.

Adding code to google3

TL;DR

Pull in the code using one of the following helper scripts.

GitHub (preferred by SecOps):

./dart/tools/pullfromgit.py --package=<package> --version=<version> [--new_package]

Pub (please use only if GitHub source is not available or not tagged):

./dart/tools/pullfrompub.py --package=<package> --version=<version> [--new_package]

Updating an existing package from Git or Pub

General guidance

  • It (probably) won’t be in google3 unless someone is using it, and it is your responsibility to ensure that the update does not break any tests. See Step-By-Step Instructions below.

  • In contrast to new packages, batching together multiple package updates is allowed when packages are coupled.

Step-by-step instructions

We’ll use the “args” package as an example

  1. Review the CHANGELOG to familiarize yourself with any changes that could break existing code.
  2. Make any necessary preemptive changes. go/using-rosie is your friend. Don’t forget replace_string!
  3. Create a client:

    mkclient -f dart_update
    
  4. Take a look at the pullfromgit.py and pullfrompub.py utilities:

    dart/tools/pullfromgit.py --helpshort
    

    or

    dart/tools/pullfrompub.py --helpshort
    
  5. Use pullfromgit.py or pullfrompub.py to automatically update the source:

    dart/tools/pullfromgit.py --package=args --version=0.12.2+2
    

    or:

    dart/tools/pullfrompub.py --package=args --version=0.12.2+2
    
  6. Repeat for any other packages.

  7. If dependencies, dev_dependencies, or transformers have been added or removed in pubspec.yaml, mirror those changes in BUILD.

  8. Make sure you’re not breaking anything by checking (in order):

    1. Unit tests (if present): blaze test //third_party/dart/args/...
    2. (Optional) dart_lang & dart_lang.presubmit Presubmit queues:

      presubmit -c $CL -p dart_lang,dart_lang.presubmit
      

      The next step (global presubmit) will also run these tests, but they run much faster here than during global. If you believe the changes may cause breakages, it may be worth completing this step.

    3. Global presubmit. See http://linkremoved/ for details:

      presubmit --train -c $CL -p all
      
  9. If your change breaks targets in google3:

    1. Generate a new patch CL with the fixes (see go/using-rosie).
    2. Run a global presubmit to verify your fix is good.
    3. Send it out to the appropriate owners:

      1. For small CLs, click the “suggest reviewers” dropdown on the right hand side of the Reviewers field. If you prefer the command-line:

        g4 findreviewers -c $CL
        
      2. For large CLs, see go/rosie. Rosie will shard your CL, run tests (if requested), select appropriate reviewers and auto-submit your CLs for you.

  10. Create and mail the CL. If unfamiliar, see one of:

    1. g4 help {change, mail, submit}
    2. Developer Workflow Codelab.
    3. g4 commands.

Examples

  • changelist …230

Adding a new package from Git or Pub

General guidance

  • Dart source code should be placed in //third_party/dart/<packagename> where <packagename> matches the package name on http://linkremoved/.
  • The layout of code within //third_party/dart/<packagename> must be identical to the pub package layout.
  • Every new package should be added in a separate CL (see go/pristinecopy)

NOTE: This example shows use of pullfrompub.py, but SecOps prefers that we use pullfromgit.py when possible. The two utilities are very similar—see pullfromgit.py --helpshort for details. Having no existing dependencies in google3 means this is wonderfully simple.

Step-by-step instructions

We’ll use the “lzma” package as an example.

  1. Follow steps 3 (“Create a client”) through 5 (“Use $TOOL to automatically update the source”) above, substituting pullfrompub.py (‘lzma’ is untagged in GitHub) and adding the --new_package flag:

    dart/tools/pullfrompub.py --new_package --package=lzma --version=0.3.0
    
  2. Check LICENSE and ensure we can use the code. See go/thirdpartylicenses for details.

  3. Fix inconsistencies between the public package and go/thirdparty rules. For example, in this case the license file is named LICENSE.txt, which goes against the rule listed that the file must be named LICENSE. Fix this before committing:

    mv LICENSE.txt LICENSE
    g4 add LICENSE; g4 revert LICENSE.txt
    
  4. Do not fix other problems, even if this means unit tests do not pass. The first commit should be the version of the code as it was downloaded (go/pristinecopy).

  5. Create BUILD and OWNERS files. You create these new or copy & update these from another package:

    pushd .. ; g4 cp args/{BUILD,OWNERS} lzma/ ; popd
    
    1. BUILD

      1. Add a dart_library target that includes all srcs in lib/, and a license attribute indicating the LICENSE file.

        dart_library(
            name = "lzma",
            srcs = glob(["lib/**/*"]),
            license = "LICENSE",
            # Unnecessary in this case, but check your pubspec.
            transformers = """
            ...""",
            deps = [...],
         )
        
      2. Ensure the licenses BUILD extension has the correct value(s).

      3. If the library requires transformers, include them.

      4. If possible, add a dart_vm_test_suite so the unit tests run in our Presubmit queues. Sometimes this would require modifying the source, which should not be done (per go/pristinecopy). If that is the case, add a TODO and fix in a subsequent CL.
        Example: args tests

      5. Run buildifier -a -v

    2. OWNERS

      1. Must list at least two full-time Googlers explicitly.
      2. If Googlers own the external package (check Pub, GitHub project, etc), include them.
  6. Create and mail the CL.

Examples

  • changelist …495

What about third_party/dart_src?

third_party/dart_src was created to support internal development of packages that do not adhere to the conventions of Dart pub packages. Parts of these directories are published as pub packages and synced to open source repos after transforming the code.

NOTE: Code that is developed in third_party/dart_src should not have a version in third_party/dart. Please adhere to the one version policy, see go/oneversion.

Dependencies on third_party/dart_src packages

If your internal application has a dependency on code in third_party/dart_src, that is fine. Just depend on the BUILD files you need and write your Dart import statements like any other internal Dart file.

Example: import 'package:third_party.dart_src.foo.bar.baz/qux.dart';

If your project has a dependency on any code in third_party/dart_src, and you intend to publish your code as open source, let’s talk. Please see below.

Developing new public packages

The common case for most packages is to be located in third_party/dart. Place your code in third_party/dart_src if:

  • Internal development is demonstrably hindered by the need to adhere to Dart pub package conventions.
  • Code that is open source will have dependencies on code in third_party/dart_src.

We are developing a simple and maintainable process for syncing code between third_party/dart_src and open source repos like GitHub. Tooling is under development to automate this process using go/copybara.

Except as otherwise noted, the content of this page is licensed under CC-BY-4.0 license. Third-party product names and logos may be the trademarks of their respective owners.