luci-app-attendedsysupgrade: Rewrite README.md for spelling, grammar, and clarity

[Bruxism]

• This PR is not from my main or master branch 💩, but a separate branch ✅

• Each commit has a valid ✒️ Signed-off-by: <my@email.address> row (via git commit --signoff) (not sure if the github provided one counts.)

• Each commit and PR title has a valid 📝 <package name>: title first line subject for packages

• Incremented 🆙 any PKG_VERSION in the Makefile (N/A)

• Tested on: (architecture, openwrt version, browser) (N/A)

• ( Preferred ) Mention: @ the original code author for feedback
  @jow-

• ( Preferred ) Screenshot or mp4 of changes:

• ( Optional ) Closes: e.g. openwrt/luci#issue-number

• ( Optional ) Depends on: e.g. openwrt/packages#pr-number in sister repo

• Description: (describe the changes proposed in this PR)

Changes were made for improvements to spelling, grammar, and clarity.

[owlsy]

This app adds OpenWrt firmware upgrade and update as well as package update functionality via its web interface.

I do find this sentence a little hard to read. I would suggest maybe rewording it to something like:

This app enables OpenWrt firmware upgrades and updates, as well as package updates, through its web interface (LuCI).

[Bruxism]

@owlsy, please let me know what you think of it. I was interested in making it succinct yet comprehensive.

[efahl]

The commits need to be squashed into one commit.

[Bruxism]

The commits need to be squashed into one commit.

I'll learn how to and work on it now. Thanks.

[owlsy]

please let me know what you think of it. I was interested in making it succinct yet comprehensive.

Sure, please see my thoughts below.

---

Upon installation, it adds a web page to the OpenWrt LuCI web interface
available at System > Attended Sysupgrade which provides controls
and configurations for when and where to send build requests.

If we want to match the typical way the OpenWrt Wiki seems to do it, I would replace:

System > Attended Sysupgrade

with:

System → Attended Sysupgrade

---

Build requests include information about the request system's
CPU architecture/target and its currently installed packages. These are sent
to an Attended SysUpgrade server (ASU) which
if available, will then respond with an install-ready custom firmware image that
includes the latest requested firmware and package updates.

I would also calm the formatting down here a little bit, perhaps just a little with not including the italics, so it goes from:

Attended SysUpgrade server (ASU)

to:

Attended SysUpgrade (ASU) server

---

Following a successful build request, the user is prompted with a link to
download a copy of the custom firmware image to their computer and the option to
immediately install the custom firmware image either with or without keeping
currently set system configurations.

I would also change the order of priority for what happens after the build request, so it would say something along the lines of:

"Following a successful build request, the user is prompted to install
the custom firmware image (with or without the existing system
configuration), as well as an option to download a copy of the
image to their own device."

---

The process per image takes between 30 seconds and 5 minutes, and may be down
for a few days during the build rollouts and peak usage that follows major
OpenWrt upgrades.

I would also keep the duration separate to the outage notice from being a sentence together, as well as include a note that this plugin has now been automatically included in OpenWrt as of 25.12.0:

"The process for building a custom firmware image can take anywhere
from 30 seconds to 5 minutes. Note, you may have some trouble during
the building process for a few days during peak usage that follows the
announcement of major OpenWrt upgrades. It is recommended to allow
a few days for the demand to subside before attempting to upgrade.

As of OpenWrt 25.12.0 and above, luci-app-attendedsysupgrade is
now installed by default."

---

More information on the backend server and how to host one are available on the
projects page: https://github.com/openwrt/asu

Let's also clarify this wording so we know it's about the Attendedsysupgrade Server:

"If you would like more information about the backend server (and how to
host one yourself), visit the ASU Server repository."

[owlsy]

Just to help you out as well, there's some requirements that need to be resolved for the pull request to be approved:

Email

❌ Author email must not be a GitHub noreply email
Expected: a real email address

❌ Signed-off-by must not be a GitHub noreply email
Expected: a real email address

These two above are letting you know that you cannot use a noreply email for your commit. If you are not comfortable using a personal email address, you could create an alternative email address for situations like this. Then, change your email address for these checks to pass.

Commit subject

❌ Commit subject must start with a lower-case word after the prefix

In this case, your commit subject needs Rewrite to be rewrite instead, and I believe less than 60 characters is the requirement.

Based on your pull request title, your commit subject (and pull request title to rename) can be:

luci-app-attendedsysupgrade: rewrite README.md for clarity

Commit message

❌ Commit message must exist

Add a commit message. You can break the message up into multiple lines, and I believe less than 75 characters per line is the requirement.

Based on the pull request comment, your commit message can be:

Changes were made to the README.md for
improvements to spelling, grammar, and clarity.

[efahl]

Approved. The changes all look good to me.

[Bruxism]

luci-app-attendedsysupgrade

luci-app-attendedsysupgrade is a plugin for the OpenWrt LuCI web interface
that facilitates updates and upgrades for both firmware and software packages.

It appears at System → Attended Sysupgrade in the web interface
where controls and configurations for when it should check for
firmware upgrades and where it should send build requests are provided.

Build requests include information about the request system's
CPU architecture/target and its currently installed packages. These are sent
to an Attended SysUpgrade server (ASU) which,
if available, will then respond with an install-ready custom firmware image that
includes the latest requested firmware and package updates.

By default, this plugin only prompts to send a build request when firmware
upgrades are detected and the user interactively selects to upgrade.

Customizable build requests are directly available via the
Search for firmware upgrades button when Advanced Mode is active.

Following a successful build request, a prompt appears with information about
the custom firmware image. The user may select to install either with
or without the existing system configuration.
There is also an option to download a separate copy
of that custom image via the web browser. Selecting Install firmware image
closes the prompt and the install proceeds with a system reboot.

ASU servers typically take between 30 seconds and 5 minutes
to process each build request and prepare a custom image.

Note

Following the announcement of a major OpenWrt upgrade, availability of
ASU servers may become limited for a few days as target builds are rolled out
and servers contend with sharply increased demand.

Further reading

If you would like more information about the backend server (and how to
host one yourself), please visit the ASU Server repository.

Support is available at the official
LuCI Attended Sysupgrade support thread.

_{luci-app-attendedsysupgrade is proudly installed in OpenWrt by default
since the
release of OpenWrt 25.12.0.}

[Bruxism]

I was inspired by the triple t in Atttended of the previous commit to do all this. I went in with the intention of following conventions by looking at the other apps' README.md, and with prospect to write something specific enough for a new user to get a firm grasp on the function and use, but vague enough to withhold changes in particularities.

Let me know if I went in a pleasant direction or if I should pare this down grossly to something that basically looks nearly like the top two paragraphs alone. I'm open to leaving it, to pare it down grossly, or to rewrite it with more markdown styling--refactoring it in a way.

I threw in that note alert as a little flare in the presumption that would help curb any concerns during major upgrade announcements. It may be gaudy, but it's gaudy with a purpose. I say that half jokingly as I imagine it comes up too often in the support threads. Still, I included a link to the official support forum as it was mentioned in the OpenWrt wiki which I hope will be found suitable to be included in the README.md. Hopefully, the note filters out much of those concerns from ending up in the forum.

@owlsy, as requested, I put in a note about the default inclusion of luci-app-attendedsysupgrade to OpenWrt 25.12.0+, and with posterity in mind, put it at the bottom in subtext about it being proudly included--something that I think will bring a little more cheer for its maintainers as further upgrades come along while also still being relevant for people that might have been upgrading from previous versions of OpenWrt and didn't understand why they didn't already have it.

A part of me wanted to use a tip alert in the italicized line about Advanced Mode, but I thought that was too 'loud' visually, and I figured anyone interested enough to be doing that for the package updates would notice it or already know it. I decided against it as I couldn't justify it like the note alert.

By the way, @owlsy, with Advanced Mode on, the prompt always says that a firmware upgrade was detected even though there is none. With the move to using apk instead of opkg and the warnings about doing full image installs instead of piecemeal package updates, it might be worth considering doing it as Advanced Mode by default when Search for upgrades is clicked--though I understand if that's asking for a lot more resources. Who knows? I already do it with owut with the occasional exception to minor luci updates, and the triggers for automatic checks of firmware upgrades and asking to upgrade before sending a build request might be suitable enough for the casual user--just some of my perspective. Should I make an issue thread about it?

[owlsy]

It looks great — I don't have any further suggestions, aside from removing some extra line breaks and trying to keep everything to the same width.

See how I would do the line breaks.

luci-app-attendedsysupgrade

luci-app-attendedsysupgrade is a plugin for the OpenWrt LuCI web interface
that facilitates updates and upgrades for both firmware and software packages.

It appears at System → Attended Sysupgrade in the web interface where
controls and configurations for when it should check for firmware upgrades
and where it should send build requests are provided.

Build requests include information about the request system's CPU
architecture/target and its currently installed packages. These are sent to an
Attended SysUpgrade server (ASU) which, if available, will then respond with
an install-ready custom firmware image that includes the latest requested
firmware and package updates.

By default, this plugin only prompts to send a build request when firmware
upgrades are detected and the user interactively selects to upgrade.

Customizable build requests are directly available via the Search for
firmware upgrades button when Advanced Mode is active.

Following a successful build request, a prompt appears with information
about the custom firmware image. The user may select to install either with
or without the existing system configuration. There is also an option to
download a separate copy of that custom image via the web browser.
Selecting Install firmware image closes the prompt and the install
proceeds with a system reboot.

ASU servers typically take between 30 seconds and 5 minutes to process
each build request and prepare a custom image.

[!NOTE]
Following the announcement of a major OpenWrt upgrade, availability of
ASU servers may become limited for a few days as target builds are rolled
out and servers contend with sharply increased demand.

Further reading

If you would like more information about the backend server (and how to host
one yourself), please visit the ASU Server repository.

Support is available at the official LuCI Attended Sysupgrade support thread.

_{luci-app-attendedsysupgrade is proudly installed in OpenWrt
by default since the release of OpenWrt 25.12.0.}

---

[…]it might be worth considering doing it as Advanced Mode by default when Search for upgrades is clicked--though I understand if that's asking for a lot more resources. […] Should I make an issue thread about it?

This would be better directed towards @efahl (who, by the way already provided a positive response to your changes) as they would have a greater understanding and authority for how luci-app-attendedsysupgrade functions, or know who else to ping and bring in for this type of discussion (not me though, I'm just a user like you).

[Bruxism]

Sorry for the messy pull request thread. I'm learning as I go here.

@owlsy, thanks for the help! The breaks would be good, but that would be in the context of this thread. It doesn't look the same as when viewing it in the repo. I was mistaken that you were the maintainer, haha. I think I tagged you because of the rule to bring a reviewer and I thought I saw you as the last commit on this app. You've gone above and beyond for me helping me here with this! Thank you!

@efahl please let me know your thoughts--particularly with the comments I had mistaking directed towards @owlsy in this comment.

[owlsy]

It doesn't look the same as when viewing it in the repo

Ah, brilliant point. I didn't think of that!

You've gone above and beyond for me helping me here with this! Thank you!

You're very welcome, my thanks to you as well for letting me and taking it on board. I only just did a similar thing as well last week with my first ever pull request, so it felt right to help you out as well. :)

[efahl]

Your recent changes all look fine. We can commit this.

[systemcrash]

"is an app" is preferred

[Bruxism]

@systemcrash I had wondered about that. I figured that since these apps can't work without LuCI that technically they're plugins, so I went with 'plugin' instead. I did notice that all of these apps go under the directory 'Applications', yet I wasn't sure.

Change made as preferred.

[github-actions]

Warning

Some formality checks failed.

Consider (re)reading submissions guidelines.

Failed checks

Issues marked with an ❌ are failing checks.

Commit 2d07d6a

• 🔶 Author name must be either a real name 'firstname lastname' or a nickname/alias/handle
  Actual: Bruxism seems to be a nickname or an alias
  Expected: a real name 'firstname lastname'
• 🔶 Commit(ter) name must be either a real name 'firstname lastname' or a nickname/alias/handle
  Actual: Bruxism seems to be a nickname or an alias
  Expected: a real name 'firstname lastname'

For more details, see the full job log.

_{Something broken? Consider providing feedback.}