[2.19] Clarify `library` usage for no-name declarations update #4390

MaryaBelanger · 2022-11-18T18:37:47Z

Changes:

Added code sample to existing library-level doc comment section
Added Don't use library directives unless attaching doc comments or annotations section
Added Don't explicitly name libraries section
Reduced part of section
Removed / modified unnecessary notes about the library directive on the Creating packages page

I thought about completely removing the part of section in Effective Dart: Usage, in favor of the more general new section "Don't explicitly name libraries", because it's not even recommended to use part of at all anymore.

The new section could add a code example similar to the one for part of that more generally illustrates "Use URI strings to refer to libraries", and the linter rule could point to that section instead.

Thoughts? @kevmoo @pq etc.

Ignores some new hints where they are not relevant due to purposely showcasing that behavior or having dead code. Also updates the diagnostic message for one updated in the dev branch.

Updated from dart-lang/linter@46a65ff

parlough · 2022-11-18T18:46:38Z

Can you run git submodule update so you don't push an outdated site-shared submodule? Also consider git rebasing on main to avoid the complicated commit history.

MaryaBelanger · 2022-11-18T18:48:16Z

@parlough Thanks for the tips, that kind of got away from me and wasn't sure what to do :/

github-actions · 2022-11-18T18:49:48Z

Visit the preview URL for this PR (updated for commit 8083f79):

https://dart-dev--pr4390-library-directive-hasb6snu.web.app

_{(expires Mon, 28 Nov 2022 20:47:38 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: d851bc446d3c4d7394c5406c6f07255afc7075f3}

parlough · 2022-11-18T18:53:15Z

@MaryaBelanger Let me know if you have any issues :)

kevmoo

Looks GREAT! Wait for at least one more approver, though!

pq

💎

pq · 2022-11-18T22:50:43Z

So awesome!

MaryaBelanger · 2022-11-19T00:36:54Z

I'm actually going to change this to a draft because it shouldn't be merged until 2.19 releases, but thanks for the reviews everyone!

munificent

This is great!

src/_guides/language/effective-dart/documentation.md

src/_guides/language/effective-dart/usage.md

MaryaBelanger · 2022-11-21T20:39:50Z

@munificent Thank you, incorporated all of that!

Going to mark as RFM

parlough

It's super exciting to finally clean up our messaging around the library directive and have some proper suggestions. Nice job :D

I have a few comments and questions. Please push back on anything that doesn't make sense :)

src/_guides/libraries/create-library-packages.md

src/_guides/language/language-tour.md

src/_guides/language/effective-dart/style.md

src/_guides/language/effective-dart/usage.md

src/_guides/language/effective-dart/style.md

parlough

Thanks for making those adjustments. I responded to the unresolved discussion and left another potential suggestion.

src/_guides/language/language-tour.md

src/_guides/libraries/create-library-packages.md

src/_guides/language/language-tour.md

Co-authored-by: Parker Lougheed <parlough@gmail.com>

parlough

Love it!

src/_guides/language/language-tour.md

Co-authored-by: Parker Lougheed <parlough@gmail.com>

@kevmoo

fixes #4314 Changes: - Added [code sample](https://lib-dir-docs.web.app/guides/language/effective-dart/documentation#consider-writing-a-library-level-doc-comment) to existing library-level doc comment section - Added [Don't use library directives unless attaching doc comments or annotations](https://lib-dir-docs.web.app/guides/language/effective-dart/usage#dont-use-library-directives-unless-attaching-doc-comments-or-annotations) section - Added [Don't explicitly name libraries](https://lib-dir-docs.web.app/guides/language/effective-dart/usage#dont-explicitly-name-libraries) section - Reduced [`part of`](https://lib-dir-docs.web.app/guides/language/effective-dart/usage#do-use-strings-in-part-of-directives) section - Removed / modified unnecessary notes about the library directive on the [Creating packages](https://lib-dir-docs.web.app/guides/libraries/create-library-packages) page I thought about completely removing the `part of` section in Effective Dart: Usage, in favor of the more general new section "Don't explicitly name libraries", because it's not even recommended to use `part of` at all anymore. The new section could add a code example similar to the one for `part of` that more generally illustrates "Use URI strings to refer to libraries", and the linter rule could point to that section instead. Thoughts? @kevmoo @pq etc. Co-authored-by: Parker Lougheed <parlough@gmail.com> Co-authored-by: Kevin Moore <kevmoo@users.noreply.github.com>

Fixes #4314 Changes: - Added [code sample](https://dart.dev/guides/language/effective-dart/documentation#consider-writing-a-library-level-doc-comment) to existing library-level doc comment section - Added [Don't use library directives unless attaching doc comments or annotations](https://dart.dev/guides/language/effective-dart/usage#dont-use-library-directives-unless-attaching-doc-comments-or-annotations) section - Added [Don't explicitly name libraries](https://dart.dev/guides/language/effective-dart/usage#dont-explicitly-name-libraries) section - Reduced [`part of`](https://dart.dev/guides/language/effective-dart/usage#do-use-strings-in-part-of-directives) section - Removed / modified unnecessary notes about the library directive on the [Creating packages](https://dart.dev/guides/libraries/create-library-packages) page Co-authored-by: Parker Lougheed <parlough@gmail.com> Co-authored-by: Kevin Moore <kevmoo@users.noreply.github.com>

MaryaBelanger and others added 9 commits November 18, 2022 09:34

Clarify library directive usage

3a066c0

fixes from tool checks

92d58bf

rebasing or something idk

7b39fc8

Fix build for new dev analysis changes (#4384)

eeb4095

Ignores some new hints where they are not relevant due to purposely showcasing that behavior or having dead code. Also updates the diagnostic message for one updated in the dev branch.

Remove jobs/hiring note from banner (#4385)

e857ab3

Drop referenced to discontinued firebase package (#4386)

c08e5d2

Update linter rules for bad-good consistency and linter 1.30 (#4383)

168a2d9

Updated from dart-lang/linter@46a65ff

Merge branch 'main' into library-directive

1331b02

remove analyzer results file

30c0398

parlough added review.copy Awaiting Copy Review review.tech Awaiting Technical Review labels Nov 18, 2022

parlough requested review from munificent and atsansone and removed request for munificent November 18, 2022 18:52

parlough changed the title ~~Clarify library usage for no-name declarations update~~ [2.19] Clarify library usage for no-name declarations update Nov 18, 2022

kevmoo approved these changes Nov 18, 2022

View reviewed changes

pq approved these changes Nov 18, 2022

View reviewed changes

MaryaBelanger marked this pull request as draft November 19, 2022 00:38

munificent approved these changes Nov 19, 2022

View reviewed changes

src/_guides/language/effective-dart/documentation.md Outdated Show resolved Hide resolved

src/_guides/language/effective-dart/usage.md Outdated Show resolved Hide resolved

src/_guides/language/effective-dart/usage.md Outdated Show resolved Hide resolved

MaryaBelanger and others added 2 commits November 21, 2022 11:40

Merge branch 'main' into library-directive

35642b3

incorporate review

8083f79

MaryaBelanger removed the review.copy Awaiting Copy Review label Nov 21, 2022

MaryaBelanger changed the base branch from v2.19 to main December 14, 2022 22:27

MaryaBelanger changed the base branch from main to v2.19 December 14, 2022 22:28

Merge branch 'v2.19' into library-directive

67ec249

parlough requested a review from atsansone December 16, 2022 08:53

parlough added review.copy Awaiting Copy Review and removed review.await-update Awaiting Updates after Edits labels Dec 16, 2022

parlough reviewed Dec 16, 2022

View reviewed changes

atsansone approved these changes Dec 19, 2022

View reviewed changes

parlough added review.await-update Awaiting Updates after Edits and removed review.copy Awaiting Copy Review labels Dec 19, 2022

MaryaBelanger mentioned this pull request Dec 20, 2022

[2.19] Update whats-new and language evolution pages #4404

Closed

parlough review

1b1ebff

MaryaBelanger added st.RFM Ready to merge or land and removed review.await-update Awaiting Updates after Edits labels Dec 20, 2022

MaryaBelanger assigned atsansone Dec 20, 2022

parlough reviewed Dec 20, 2022

View reviewed changes

src/_guides/language/language-tour.md Outdated Show resolved Hide resolved

src/_guides/libraries/create-library-packages.md Outdated Show resolved Hide resolved

src/_guides/language/language-tour.md Outdated Show resolved Hide resolved

parlough added review.await-update Awaiting Updates after Edits and removed st.RFM Ready to merge or land labels Dec 20, 2022

MaryaBelanger and others added 2 commits December 20, 2022 15:10

Apply suggestions from code review

ad02cc5

Co-authored-by: Parker Lougheed <parlough@gmail.com>

remove unnamed library mention from language tour

fabcc78

MaryaBelanger added st.RFM Ready to merge or land and removed review.await-update Awaiting Updates after Edits labels Dec 20, 2022

parlough approved these changes Dec 20, 2022

View reviewed changes

src/_guides/language/language-tour.md Outdated Show resolved Hide resolved

Update src/_guides/language/language-tour.md

1a5cefc

Co-authored-by: Parker Lougheed <parlough@gmail.com>

atsansone merged commit 458bcdb into v2.19 Dec 20, 2022

parlough deleted the library-directive branch January 24, 2023 17:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[2.19] Clarify `library` usage for no-name declarations update #4390

[2.19] Clarify `library` usage for no-name declarations update #4390

MaryaBelanger commented Nov 18, 2022 •

edited

Loading

parlough commented Nov 18, 2022 •

edited

Loading

MaryaBelanger commented Nov 18, 2022

github-actions bot commented Nov 18, 2022 •

edited

Loading

parlough commented Nov 18, 2022

kevmoo left a comment

pq left a comment

pq commented Nov 18, 2022

MaryaBelanger commented Nov 19, 2022

munificent left a comment

MaryaBelanger commented Nov 21, 2022

parlough left a comment

parlough left a comment

parlough left a comment

[2.19] Clarify library usage for no-name declarations update #4390

[2.19] Clarify library usage for no-name declarations update #4390

Conversation

MaryaBelanger commented Nov 18, 2022 • edited Loading

parlough commented Nov 18, 2022 • edited Loading

MaryaBelanger commented Nov 18, 2022

github-actions bot commented Nov 18, 2022 • edited Loading

parlough commented Nov 18, 2022

kevmoo left a comment

Choose a reason for hiding this comment

pq left a comment

Choose a reason for hiding this comment

pq commented Nov 18, 2022

MaryaBelanger commented Nov 19, 2022

munificent left a comment

Choose a reason for hiding this comment

MaryaBelanger commented Nov 21, 2022

parlough left a comment

Choose a reason for hiding this comment

parlough left a comment

Choose a reason for hiding this comment

parlough left a comment

Choose a reason for hiding this comment

[2.19] Clarify `library` usage for no-name declarations update #4390

[2.19] Clarify `library` usage for no-name declarations update #4390

MaryaBelanger commented Nov 18, 2022 •

edited

Loading

parlough commented Nov 18, 2022 •

edited

Loading

github-actions bot commented Nov 18, 2022 •

edited

Loading