WIP: add guidelines for GNOME Shell extensions

salimma commented

2024-12-19 02:59:03 +00:00

Owner

This is part of https://fedoraproject.org/wiki/Changes/GnomeShellExtensionDependencyGenerator

and should not be committed until the Change is accepted and the
implementation is done

Signed-off-by: Michel Lind salimma@fedoraproject.org

This is part of https://fedoraproject.org/wiki/Changes/GnomeShellExtensionDependencyGenerator and should not be committed until the Change is accepted and the implementation is done Signed-off-by: Michel Lind <salimma@fedoraproject.org>

james commented

2025-01-16 16:43:14 +00:00

Owner

Metadata Update from @james:

Pull-request tagged with: needinfo

**Metadata Update from @james**: - Pull-request tagged with: needinfo

james commented

2025-01-16 16:44:44 +00:00

Owner

Text looks fine, I think we prefer to add line breaks so that small future diffs don't change an entire paragraph of text?

Also marking it as needinfo, which is for the change being accepted/implemented.

Text looks fine, I think we prefer to add line breaks so that small future diffs don't change an entire paragraph of text? Also marking it as needinfo, which is for the change being accepted/implemented.

ferdnyc commented

2025-01-19 07:27:50 +00:00

Member

Specifically, I'd suggest semantic newlines,
aka "one sentence per line", which might look like this:

= GNOME Shell extensions

https://extensions.gnome.org/about/[GNOME Shell extensions]
are small pieces of code written by third party developers
that modify the way GNOME works.

== Requires

Extensions are marked as compatible with specific versions of GNOME Shell
in their `metadata.json`.
We have historically not required
that the packaged extension express this dependency,
and as a result,
extensions that have not been updated for a newer GNOME Shell
might install just fine but then won't activate.

From Fedora Linux 42 and up,
a dependency generator is automatically run as part of the package build
to add install-time dependencies on the versions of GNOME Shell
the extension's `metadata.json` claims to support;
as such, for Fedora 42 and above
extension packages _MUST_ declare the version of GNOME Shell they support.
This is a no-op for packagers.

For Fedora Linux 41 and below, and EPEL,
declaring the version of GNOME Shell an extension supports
is a _SHOULD_ rather than a must.

(Writing with a goal of keeping each sentence
to "around" one or two ~80-character lines max
is also a good practice.
Shorter sentences can make text more accessible to a wider audience.
Some readers, including non-native English readers,
may have trouble following very long sentences.

Semantic-newline formatting makes sentence length more obvious.
For example, the entire second paragraph of 'Requires'
(7 semantic lines) is only two sentences long.
The first 6 lines are all one sentence.
The other sentence fits on the very last line.
That first sentence might be a bit daunting for some readers.)

Specifically, I'd suggest [semantic newlines](https://sembr.org), aka "one sentence per line", which might look like this: ```adoc = GNOME Shell extensions https://extensions.gnome.org/about/[GNOME Shell extensions] are small pieces of code written by third party developers that modify the way GNOME works. == Requires Extensions are marked as compatible with specific versions of GNOME Shell in their `metadata.json`. We have historically not required that the packaged extension express this dependency, and as a result, extensions that have not been updated for a newer GNOME Shell might install just fine but then won't activate. From Fedora Linux 42 and up, a dependency generator is automatically run as part of the package build to add install-time dependencies on the versions of GNOME Shell the extension's `metadata.json` claims to support; as such, for Fedora 42 and above extension packages _MUST_ declare the version of GNOME Shell they support. This is a no-op for packagers. For Fedora Linux 41 and below, and EPEL, declaring the version of GNOME Shell an extension supports is a _SHOULD_ rather than a must. ``` (Writing with a _goal_ of keeping each sentence to "around" one or two ~80-character lines max is also a good practice. Shorter sentences can make text more accessible to a wider audience. Some readers, including non-native English readers, may have trouble following very long sentences. Semantic-newline formatting makes sentence length more obvious. For example, the entire second paragraph of 'Requires' (7 semantic lines) is only two sentences long. The first 6 lines are all one sentence. The other sentence fits on the very last line. That first sentence might be a bit daunting for some readers.)

ferdnyc commented

2025-01-19 07:29:37 +00:00

Member

Aaaaand of course, Pagure doesn't join my semantically-broken comment lines the way a MarkDown processor is supposed to. :-/

decathorpe commented

2025-01-20 20:58:04 +00:00

Owner

Specifically, I'd suggest semantic newlines

Yes, we already try to apply SemBR to all new guidelines documents (and those that are rewritten).

> Specifically, I'd suggest semantic newlines Yes, we already try to apply SemBR to all new guidelines documents (and those that are rewritten).

ngompa commented

2026-02-04 16:08:40 +00:00

Owner

Can we get this refreshed and landed? The dependency generator now exists in F42+ and EPEL10.

carlwgeorge commented

2026-03-19 22:25:36 +00:00

Owner

Strong +1 to switching this to SemBr, as I can't even comfortably review this from the "files changed" tab or do coherent inline review comments.

From Fedora Linux 42 and up, a dependency generator is automatically run as part of the package build

This does not seem to be true. Many packaged extensions don't have the dependency. I suspect this requires opting in via a BuildRequires on gnome-shell-rpm-generators, and if that's the case the guidelines should describe that.

for Fedora 42 and above extension packages MUST declare the version of GNOME Shell they support.

I'd prefer this to be SHOULD or even MAY. On my extension packages I intentionally only set an explicit (not generated) lower bound. It's quite common for an extension to keep working on new GNOME versions that aren't mentioned in metadata.json. Not setting an upper bound in the RPM metadata means that users can easily test the extension with newer GNOME versions by setting the dconf key /org/gnome/shell/disable-extension-version-validation to true. This capability is highly beneficial for collaboration with the extension's upstream, as users can easily report that it works, or share the corresponding GJS error message when it doesn't. By comparison, the RPM dependency error from using the generator would be completely worthless to upstream as it would just report what is already known from the metadata.json file.

Could we compromise and have the policy be MUST on the lower bound, and SHOULD for the upper bound? The generator would cover both, and opting out of the generator would still be compliant if you set the lower bound manually.

This is a no-op for packagers.

It's not clear to me what this means. Could it be rephrased or elaborated?

For Fedora Linux 41 and below

F41 is EOL now, so new guidelines probably shouldn't reference it.

Strong +1 to switching this to SemBr, as I can't even comfortably review this from the "files changed" tab or do coherent inline review comments. > From Fedora Linux 42 and up, a dependency generator is automatically run as part of the package build This does not seem to be true. Many packaged extensions don't have the dependency. I suspect this requires opting in via a BuildRequires on `gnome-shell-rpm-generators`, and if that's the case the guidelines should describe that. > for Fedora 42 and above extension packages _MUST_ declare the version of GNOME Shell they support. I'd prefer this to be SHOULD or even MAY. On my extension packages I intentionally only set an explicit (not generated) lower bound. It's quite common for an extension to keep working on new GNOME versions that aren't mentioned in `metadata.json`. Not setting an upper bound in the RPM metadata means that users can easily test the extension with newer GNOME versions by setting the dconf key `/org/gnome/shell/disable-extension-version-validation` to true. This capability is highly beneficial for collaboration with the extension's upstream, as users can easily report that it works, or share the corresponding GJS error message when it doesn't. By comparison, the RPM dependency error from using the generator would be completely worthless to upstream as it would just report what is already known from the `metadata.json` file. Could we compromise and have the policy be MUST on the lower bound, and SHOULD for the upper bound? The generator would cover both, and opting out of the generator would still be compliant if you set the lower bound manually. > This is a no-op for packagers. It's not clear to me what this means. Could it be rephrased or elaborated? > For Fedora Linux 41 and below F41 is EOL now, so new guidelines probably shouldn't reference it.

This pull request is broken due to missing fork information.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin gnome-shell-extensions:gnome-shell-extensions

git switch gnome-shell-extensions

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main

git merge --no-ff gnome-shell-extensions

git switch gnome-shell-extensions

git rebase main

git switch main

git merge --ff-only gnome-shell-extensions

git switch gnome-shell-extensions

git rebase main

git switch main

git merge --no-ff gnome-shell-extensions

git switch main

git merge --squash gnome-shell-extensions

git switch main

git merge --ff-only gnome-shell-extensions

git switch main

git merge gnome-shell-extensions

git push origin main

Rows
Columns

WIP: add guidelines for GNOME Shell extensions #1425

Checkout

Merge