Skip to content

Commit 00ebfa0

Browse files
AndrewJakubowiczaugustjkjustinfagnani
authored
Release Lit v3 pre-release docs with blog post (#1116)
* Copy over all unversioned content into a versioned directory The only file changed in the move is the root `docs.json` file. Instead a `v2.json` file was added. * Add initial build-unversioned-docs script. This copies over and adds the correct permalinks to the selected version content. Currently moving `v2` -> `unversioned`. * Fix wireit so npm run dev doesnt spin infinitely. * Add rel=canonical link from latestVersion to unversioned page. * Make all authored cross links versioned. Unversioned links will be generated automatically by the generated unversioned pages. * Add fixUnversionedCrossLinks so unversioned cross-linking work. This works by piping all the content through a function that will fix cross links on unversioned pages. * Add integration tests checking added features. * unblock failing link by adding it to the known good list. * Fix api shortcode such that it uses a versioned URL The versioned URL is stripped for unversioned URLs by our tooling. Add a test to confirm this behavior. * Apply code review feedback. Thank you! * Code review feedback from Justin - Replaced sync fs with async fs. - Made lightweight YAML parser more robust using regex. * Add undiscoverable v3 generated documentation. Currently the Lit 3 commit being used is d04a3e30eb3ae3520fb0ac163fb5ddbbf6030620 because lit/lit#3894 fixes building Lit 3. API docs are visible at /docs/api/v3/ * Explicitly bump node heap size. This will hopefully avoid the Github Actions failures. * Add types/codemirror to fix TS 5 error. Thank you Augustine! Re-ran generator with no content changes. * Remove unneeded dependency Co-authored-by: Augustine Kim <[email protected]> * Code review feedback with Wireit env. * Fix formatting & filter out v3/api/index.html page * Copy over v2 docs to v3 unchanged. * Add banner and config * Fix all cross links in v3 docs to be v3 specific. - Find replace all /v2/ with /v3/ - Replace api shortcode with api-v3 shortcode - linking to v3 api docs * Add Lit 3.0 upgrade guide - first attempt. * Add v3 to the Lit.dev dropdown. * Upstream ssr client-usage docs to v3 page. This makes the page a duplicate of the v2 page. Git for some reason did not include these changes when merging from main. * Remove pre-release v3 docs from search index * Add version links so that v2 <-> v3 changing doesnt change page. A user on v2 docs for a certain page should remain on that page when switching to v3 and vice-versa. This change makes it so switching between v2 and v3 will keep you on the same page, but provide the different versions of the page. Tested manually on every single page. * Update tools section for v3 (#1118) * Update tools section for v3 * Better wording for versions tested * Add pre-releases banner content to v3 banner. * Update packages/lit-dev-content/site/docs/v3/releases/upgrade.md Co-authored-by: Augustine Kim <[email protected]> * Update packages/lit-dev-content/site/docs/v3/releases/upgrade.md Co-authored-by: Augustine Kim <[email protected]> * Lit 3.0 pre-releases blog post (#1115) * Lit 3.0 pre-releases blog post * Apply suggestions from code review * Add link to upgrade guide --------- Co-authored-by: Augustine Kim <[email protected]> * Remove a small paragraph that didn't really make sense from upgrade. * Add missing word "can". * Fix blog dropdown referring 3.0 -> v3 --------- Co-authored-by: Augustine Kim <[email protected]> Co-authored-by: Justin Fagnani <[email protected]>
1 parent 09800da commit 00ebfa0

File tree

110 files changed

+11626
-155
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

110 files changed

+11626
-155
lines changed

packages/lit-dev-content/.eleventy.js

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -445,6 +445,14 @@ ${content}
445445
});
446446
};
447447

448+
addApiShortcode(
449+
'api-v3',
450+
'/docs/v3/api',
451+
JSON.parse(
452+
fsSync.readFileSync('../lit-dev-api/api-data/lit-3/symbols.json', 'utf8')
453+
)
454+
);
455+
448456
addApiShortcode(
449457
'api',
450458
'/docs/v2/api',

packages/lit-dev-content/site/_includes/default.html

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,10 @@
2828
{% endif %}
2929
{% inlinejs "global/dsd-polyfill.js" %}
3030

31-
{% if selectedVersion !== latestVersion %}
31+
{% if selectedVersion == "v1" %}
3232
<link rel="canonical" href="{{ versions[latestVersion].path }}/{{ versionLinks[latestVersion] }}">
33+
{% endif %}
34+
{% if selectedVersion !== latestVersion %}
3335
{% inlinejs "components/litdev-banner.js" %}
3436
{% endif %}
3537

@@ -65,12 +67,17 @@
6567

6668
{% include 'header.html' %}
6769

68-
{% if selectedVersion !== latestVersion %}
70+
{% if selectedVersion !== latestVersion and selectedVersion !== "v3" %}
6971
<litdev-banner>
7072
You're viewing docs for an older version of Lit. Click
7173
<a href="{{ versions[latestVersion].path }}/{{ versionLinks[latestVersion] }}">
7274
here</a> for the latest version.
7375
</litdev-banner>
76+
{% elif selectedVersion === "v3" %}
77+
<litdev-banner>
78+
You're viewing docs for a pre-release version of Lit. Read the Lit 3.0 pre-releases
79+
announcement <a href="/blog/2023-05-15-lit-3.0-prerelease/">here</a>.
80+
</litdev-banner>
7481
{% endif %}
7582

7683
<main {% if not page.url.includes('/docs/')
Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
tags: blogPosts
3+
layout: blog-post.html
4+
title: "Announcing Lit 3.0 Pre-releases"
5+
summary: "Get an early look at the upcoming Lit 3.0 release."
6+
date: 2023-05-15
7+
author:
8+
- justin-fagnani
9+
---
10+
11+
# Announcing Lit 3.0 Pre-releases
12+
13+
The Lit team is excited to announce the first pre-releases of Lit 3.0!
14+
15+
Lit 3.0 is our first major version since [introducing the unified Lit project and Lit 2.0](https://lit.dev/blog/2021-04-21-lit-2.0-meet-lit-all-over-again/) two years ago. We really value stability and backwards compatibility for our community, so we've focused on adding new features with minor versions of the core libraries and new labs packages, and not making any breaking changes.
16+
17+
But the time is right for just a few breaking changes that will improve development velocity and testing stability on the core Lit project.
18+
19+
## Changes
20+
21+
Lit 3.0 adds no new features, because new features are generally not breaking changes and can be added in minor versions, according to semver. The Lit 3.0 release is an opportunity to make a few breaking changes that trim out some technical debt to unlock new features we have scheduled for our 3.x release series.
22+
23+
The Lit 3.0 changes are mostly in browser support, removing deprecated APIs, and how packages are published. If you run Lit 2.x with no deprecation warnings, this should be a seamless upgrade!
24+
25+
Here are the biggest things Lit 3.0 changes:
26+
- IE11 is no longer supported.
27+
- Lit's npm modules are now published as ES2021.
28+
- APIs deprecated during the Lit 1.x release timeframe have been removed.
29+
- SSR hydration support modules were moved to the `@lit-labs/ssr-client` package.
30+
31+
A preview of the [Lit v2 to v3 upgrade guide](/docs/v3/releases/upgrade/) is available on the site.
32+
33+
Detailed change logs can be found [on GitHub](https://github.com/lit/lit/releases?q=%22-pre.0%22&expanded=true).
34+
35+
## Trying the Pre-releases
36+
37+
We would love your help testing the new versions, to ensure a smooth upgrade process with the final releases. We're especially interested in making sure the new language version works with your toolchains. We expect some users may need to upgrade their tooling to the latest versions.
38+
39+
You can try the pre-releases out by updating your package.json file to include the following:
40+
41+
```json
42+
"lit": "^3.0.0-pre.0"
43+
"lit-html": "^3.0.0-pre.0"
44+
"lit-element": "^4.0.0-pre.0"
45+
"@lit/reactive-element": "^2.0.0-pre.0"
46+
```
47+
48+
You can also use the `pre` npm tag, like `npm i lit@pre`.
49+
50+
All other packages, like labs packages, have pre-release versions too that depend on the pre-release core libraries. If you depend on those you'll have to update them too. If you're more daring you can use npm overrides to select the pre-releases even for dependencies. This should work for most dependencies.
51+
52+
Even if dependencies are using Lit 2.x, the good news is that Lit 2.x and Lit 3.x are interoperable, because:
53+
1. The inherent interoperability web components: components built with different libraries work together, including those build with different versions of Lit.
54+
2. We made interop of core features like templates and directives a priority for Lit 2. You can share templates, directives, decorators, etc., across Lit versions.
55+
56+
## Docs
57+
58+
We are preparing new docs for 3.0 on [lit.dev](https://lit.dev). Even though these will be mostly the same as 2.x, we are clarifying the browser and toolchain support, and want to make it easy to select the right docs set for the version you're using to enable future changes specific to to 3.x. At the 3.0 launch, we’ll archive the 2.x docs (but they will remain available in the doc version dropdown, as will 1.x). During the 3.0 pre-release phase, 2.x will remain the default, and you can select v3 from the dropdown next to the Documentation tab.
59+
60+
## Feedback
61+
62+
We hope you enjoy Lit 3.0! If you have questions or feedback, please let us know in [GitHub issues](https://github.com/lit/lit/issues) or on our [Lit and Friends Discord](https://lit.dev/discord/).
63+
64+
**Thanks!,**
65+
66+
**-The Lit Team**

packages/lit-dev-content/site/docs/v2/components/decorators.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ eleventyNavigation:
66
order: 8
77
versionLinks:
88
v1: components/decorators/
9+
v3: components/decorators/
910
---
1011

1112
Decorators are special functions that can modify the behavior of classes, class methods, and class fields. Lit uses decorators to provide declarative APIs for things like registering elements, reactive properties, and queries.

packages/lit-dev-content/site/docs/v2/components/defining.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ eleventyNavigation:
66
order: 1
77
versionLinks:
88
v1: components/templates/
9+
v3: components/defining/
910
---
1011

1112
Define a Lit component by creating a class extending `LitElement` and registering your class with the browser:

packages/lit-dev-content/site/docs/v2/components/events.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ eleventyNavigation:
66
order: 7
77
versionLinks:
88
v1: components/events/
9+
v3: components/events/
910
---
1011

1112
Events are the standard way that elements communicate changes. These changes typically occur due to user interaction. For example, a button dispatches a click event when a user clicks on it; an input dispatches a change event when the user enters a value in it.

packages/lit-dev-content/site/docs/v2/components/lifecycle.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ eleventyNavigation:
66
order: 5
77
versionLinks:
88
v1: components/lifecycle/
9+
v3: components/lifecycle/
910
---
1011

1112
Lit components use the standard custom element lifecycle methods. In addition Lit introduces a reactive update cycle that renders changes to DOM when reactive properties change.

packages/lit-dev-content/site/docs/v2/components/overview.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ eleventyNavigation:
66
order: 0
77
versionLinks:
88
v1: components/templates/
9+
v3: components/overview/
910
---
1011

1112
A Lit component is a reusable piece of UI. You can think of a Lit component as a container that has some state and that displays a UI based on its state. It can also react to user input, fire events—anything you'd expect a UI component to do. And a Lit component is an HTML element, so it has all of the standard element APIs.

packages/lit-dev-content/site/docs/v2/components/properties.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ eleventyNavigation:
66
order: 3
77
versionLinks:
88
v1: components/properties/
9+
v3: components/properties/
910
---
1011

1112
Lit components receive input and store their state as JavaScript class fields or properties. *Reactive properties* are properties that can trigger the reactive update cycle when changed, re-rendering the component, and optionally be read or written to attributes.

packages/lit-dev-content/site/docs/v2/components/rendering.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ eleventyNavigation:
66
order: 2
77
versionLinks:
88
v1: components/templates/
9+
v3: components/rendering/
910
---
1011

1112
Add a template to your component to define what it should render. Templates can include _expressions_, which are placeholders for dynamic content.

0 commit comments

Comments
 (0)