Release 1.32.0 doc changes

Jcahilltorre commented 2 months ago

Release 1.32.0 branch

Adds all the documentation changes related to Unit Release 1.32.0

Planned changes:

Version change
Date change
1.32.0 Release news doc
wasm-wasi-component news doc
wasm-wasi-component doc changes
...

This PR is a work in progress. The planned changes above will be updated as we go.

netlify[bot] commented 2 months ago

Deploy Preview for nginx-unit ready!

Name	Link
Latest commit	ce6127ae90529882f7d0bf70075d920dd946152e
Latest deploy log	https://app.netlify.com/sites/nginx-unit/deploys/65ddee87a064b3000811830b
Deploy Preview	https://deploy-preview-102--nginx-unit.netlify.app/howto/falcon
Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

ac000 commented 2 months ago

Release 1.32.0 branch

Adds all the documentation changes related to Unit Release 1.32.0

...

1.32.0 Release news doc

wasm-wasi-component news doc

wasm-wasi-component doc changes

Is there some missing commits? or is that the more to come?

tippexs commented 2 months ago

.

There is more to come. We are currently working on the commits.

ac000 commented 2 months ago

A couple of issues I see here

1) Line lengths

I think we should stick to keeping our lines < 80 characters wide where possible, obviously commands, URL's etc should not be wrapped.

2) White space damage

These patches introduce a fair amount of excess whitespace

$ git diff --check master.. | grep -v ^+ # because the highlighted whitespace won't show here
source/configuration.rst:5137: trailing whitespace.
source/configuration.rst:5140: trailing whitespace.
source/configuration.rst:5141: trailing whitespace.
source/configuration.rst:5149: trailing whitespace.
source/configuration.rst:5150: trailing whitespace.
source/configuration.rst:5152: trailing whitespace.
source/configuration.rst:5153: trailing whitespace.
source/configuration.rst:5154: trailing whitespace.
source/configuration.rst:5163: trailing whitespace.
source/configuration.rst:5167: trailing whitespace.
source/configuration.rst:5168: trailing whitespace.
source/configuration.rst:5169: trailing whitespace.
source/configuration.rst:5171: trailing whitespace.
source/configuration.rst:5172: trailing whitespace.
source/configuration.rst:5177: trailing whitespace.
source/configuration.rst:5183: trailing whitespace.
source/configuration.rst:5189: trailing whitespace.
source/configuration.rst:5197: trailing whitespace.
source/configuration.rst:5282: trailing whitespace.
source/configuration.rst:5287: trailing whitespace.
source/configuration.rst:5288: trailing whitespace.
source/configuration.rst:5290: trailing whitespace.
source/configuration.rst:5291: trailing whitespace.
source/howto/source.rst:155: trailing whitespace.
source/howto/source.rst:158: trailing whitespace.
source/howto/source.rst:178: trailing whitespace.
source/howto/source.rst:180: trailing whitespace.
source/howto/source.rst:184: trailing whitespace.
source/howto/source.rst:187: trailing whitespace.
source/howto/source.rst:190: trailing whitespace.
source/howto/source.rst:192: trailing whitespace.
source/howto/source.rst:194: trailing whitespace.
source/howto/source.rst:196: trailing whitespace.
source/howto/source.rst:198: trailing whitespace.
source/howto/source.rst:200: trailing whitespace.
source/howto/source.rst:201: trailing whitespace.
source/howto/source.rst:744: trailing whitespace.
source/news/2024/index.rst:9: trailing whitespace.
source/news/2024/unit-1.32.0-released.rst:15: trailing whitespace.
source/news/2024/unit-1.32.0-released.rst:27: trailing whitespace.
source/news/2024/unit-1.32.0-released.rst:29: trailing whitespace.
source/news/2024/unit-1.32.0-released.rst:47: trailing whitespace.
source/news/2024/unit-1.32.0-released.rst:55: trailing whitespace.

ac000 commented 2 months ago

White space issue can be fixed via

$ git rebase --whitespace=fix master

Jcahilltorre commented 2 months ago

A couple of issues I see here

Line lengths

I think we should stick to keeping our lines < 80 characters wide where possible, obviously commands, URL's etc should not be wrapped.

White space damage

These patches introduce a fair amount of excess whitespace
$ git diff --check master.. | grep -v ^+ # because the highlighted whitespace won't show here

Trailing spaces slipped in when moving content from Confluence I will resolved those.

Line length is not an issue in my book. We don't enforce in any doc repos. We disable the checks in linter. We can discuss it and make a decision.

ac000 commented 2 months ago

On Thu, 22 Feb 2024 14:05:57 -0800 Travis Martin @.***> wrote:

@@ -726,6 +743,17 @@ and place module-specific instructions in the Makefile.
.. tab:: WebAssembly
.. _modules-webassembly:

When you run :program:./configure wasm-wasi-component,

the script configures a module to support running WebAssembly applications on

I wonder we should s/applications/components/ to disambiguate from modules?.

ac000 commented 2 months ago

You should drop cherrypick PR106 as I already merged it...

callahad commented 2 months ago

Feedback on current announcement draft. Adding checkboxes in case someone (@Jcahilltorre @tippexs ?) wants to track addressing thing in the draft.

At a very high level:

[ ] We need to write for an audience that doesn't know anything about Unit and and doesn't care about its history. For example, we should:
- [ ] Open with a single sentence stating what Unit is.
- [ ] Lead with WASI 0.2 / Preview 2 support before we say anything about the deprecated bespoke Wasm support. Nobody cares about 1.31, they care about what 1.32 means for WebAssembly in Unit.
- [ ] Revise the feature bullets to make sense for someone who isn't on the team. E.g., "conditional access logging" and "added a new variable request_id" don't tell me anything about what this is or why I should care.
- [ ] The same applies later on (e.g., "Node JS Language Module enhancements" tells me nothing. And we had similarly notable fixes for Python and Ruby.)
[ ] Sequence the sections by order of importance. Wasm first. GitHub toward the end.
[x] The Changes in Behavior section should talk more about the Docker change; it’s pretty significant. All logs are going to stderr instead of stdout now. If we think it’s useful to separately route access logs to stdout, we should either make that the default, or we should provide an example for how it can be done.

Other things:

[x] Verify with Alex Crichton if/how he'd like to be credited (e.g., should we mention "of Fermyon"?)
[x] Mention sources.nginx.org/unit/ for tarballs, old URLs still work.
[ ] The GitHub section should probably link to things in a few places (e.g., the Docs repo)
[ ] Should the NJS section bold keywords like "pass", "rewrite", and "Cache-Control"
[ ] Be more vague about the forthcoming blogpost; don't lock us in to a title yet :)
[x] "Node.js" not "Node JS"
[ ] Do we want to summarize other folks' contributions?

lcrilly commented 2 months ago

@callahad wrote:

We need to write for an audience that doesn't know anything about Unit and and doesn't care about its history.

I disagree. I consider release notes are read by those interested in what's new and what's changed. By definition, these are existing Unit users.

callahad commented 2 months ago

@lcrilly I responded to that over in https://github.com/nginx/unit-docs/pull/110#discussion_r1503165393 if you'd like to consider my rationale here

nginx / unit-docs