PR#17: Use semantic linebreaks - fedora-docs/flatpak

fedora-docs / flatpak

#17 Use semantic linebreaks

Closed a year ago by oturpe. Opened a year ago by oturpe.

fedora-docs/ oturpe/flatpak sembr into master

Use semantic linebreaks

Otto Liljalaakso • a year ago

5f66937

modules/ROOT/pages/concepts.adoc

file modified

+33 -12

		`@@ -3,30 +3,51 @@`
		`= Flatpak Concepts`

		`== Application ID`
		- Every application needs a unique application ID, based on a reversed domain name. For example `org.gnome.Maps`.
		`- All resources exported by the application must be prefixed by this identifier. This includes the`
		`- https://standards.freedesktop.org/desktop-entry-spec/latest/[desktop file], the appdata file for the`
		`- application, and any icons referenced by the desktop file.`
		`+ Every application needs a unique application ID, based on a reversed domain name.`
		+ For example `org.gnome.Maps`.
		`+ All resources exported by the application must be prefixed by this identifier.`
		`+ This includes the https://standards.freedesktop.org/desktop-entry-spec/latest/[desktop file],`
		`+ the appdata file for the application,`
		`+ and any icons referenced by the desktop file.`

		`See xref:in-depth.adoc#_picking_an_application_id[Picking an application ID].`

		`== Appdata`
		`The appdata file for a Flatpak is used for displaying information about the application prior to`
		`- installation. See https://fedoraproject.org/wiki/Packaging:AppData[Fedora Packaging Guidelines for AppData Files].`
		`+ installation.`
		`+ See https://fedoraproject.org/wiki/Packaging:AppData[Fedora Packaging Guidelines for AppData Files].`

		`== Runtimes and bundled libraries`
		`When a Flatpak is executed, the files that the application see come from two places:`

		- * The Flatpak _runtime_, mounted at `/usr`. This contains libraries and data files shared by all Fedora Flatpaks. There is one runtime version for each Fedora release.
		- * The Flatpak _application_, mounted at `/app`. This contains the application code itself, but also contains any libraries that are bundled with the application. The application and libraries must be rebuilt with this prefix - this is done by including them in your module.
		+ * The Flatpak _runtime_, mounted at `/usr`.
		`+ This contains libraries and data files shared by all Fedora Flatpaks.`
		`+ There is one runtime version for each Fedora release.`
		`+`
		+ * The Flatpak _application_, mounted at `/app`.
		`+ This contains the application code itself,`
		`+ but also contains any libraries that are bundled with the application.`
		`+ The application and libraries must be rebuilt with this prefix —`
		`+ this is done by including them in your module.`

		`== Modules`
		`- Packaging flatpaks in Fedora makes use of https://docs.fedoraproject.org/en-US/modularity/[Modularity]. The application and bundled libraries are built in a module - this gives a couple of advantages:`
		`+ Packaging flatpaks in Fedora makes use of https://docs.fedoraproject.org/en-US/modularity/[Modularity].`
		`+ The application and bundled libraries are built in a module - this gives a couple of advantages:`

		- * The module has a different buildroot configuration with macros that result in RPMs in the module being built with a prefix of `/app`.
		- * The application author is in control of the particular versions of libraries that are included. Even if your application is built on the `f{MAJOROSVER}` runtime, you can use libraries from a newer or older version of Fedora, if required by your application.
		`+ * The module has a different buildroot configuration`
		+ with macros that result in RPMs in the module being built with a prefix of `/app`.
		`+`
		`+ * The application author is in control of the particular versions of libraries that are included.`
		+ Even if your application is built on the `f{MAJOROSVER}` runtime,
		`+ you can use libraries from a newer or older version of Fedora,`
		`+ if required by your application.`

		- Note that Flatpak modules will not work outside the Flatpak context, since they contain RPMs rebuilt with a prefix of `/app` with the same name as system ibraries - you cannot use `dnf module enable` to install them.
		`+ Note that Flatpak modules will not work outside the Flatpak context,`
		+ since they contain RPMs rebuilt with a prefix of `/app` with the same name as system ibraries —
		+ you cannot use `dnf module enable` to install them.

		`== OCI Images`
		`- For Fedora, Flatpak runtimes and applications are built as https://github.com/opencontainers/image-spec/blob/master/spec.md[OCI Images] and distributed via https://registry.fedoraproject.org. This allows Flatpaks to be handled in a very similar way to server side containers. (Flatpaks are also commonly distributed via https://ostree.readthedocs.io/en/latest/[ostree].)`
		`+ For Fedora, Flatpak runtimes and applications are built as https://github.com/opencontainers/image-spec/blob/master/spec.md[OCI Images]`
		`+ and distributed via https://registry.fedoraproject.org.`
		`+ This allows Flatpaks to be handled in a very similar way to server side containers.`
		`+ (Flatpaks are also commonly distributed via https://ostree.readthedocs.io/en/latest/[ostree].)`

modules/ROOT/pages/faq.adoc

file modified

+6 -2

		`@@ -2,6 +2,10 @@`

		`[qanda]`
		`Can I see a built preview of this template to get a better idea about the result?::`
		`- Of course you can! Just look at the README of the repository — it should tell you everything.`
		`+ Of course you can!`
		`+ Just look at the README of the repository — it should tell you everything.`
		`Is writing documentation hard and dreadful?::`
		`- Absolutely not. Writing documentation in asciidoc is very simple and straighforward. And in fact, writing documentation makes you very happy. Just try and see for yourself!`
		`+ Absolutely not.`
		`+ Writing documentation in asciidoc is very simple and straighforward.`
		`+ And in fact, writing documentation makes you very happy.`
		`+ Just try and see for yourself!`

modules/ROOT/pages/in-depth.adoc

file modified

+49 -15

		`@@ -4,7 +4,8 @@`

		`== Is your application suitable?`

		`- Most graphical applications can be made into a Flatpak without modification, though creating a sandboxed Flatpak that prevents the application from doing arbitrary things to the user’s account is more likely to require code changes.`
		`+ Most graphical applications can be made into a Flatpak without modification,`
		`+ though creating a sandboxed Flatpak that prevents the application from doing arbitrary things to the user’s account is more likely to require code changes.`

		`Some things that could make an application not work well as a Flatpak:`

		`@@ -15,18 +16,47 @@`
		`To select an appropriate an xref:concepts.adoc#application_id[application ID]:`

		`* If the application already has a desktop file of this form, that is the application ID.`
		- * If the application exports any D-Bus services (Look for files in `/usr/share/dbus-1/services/` - though an application can export D-Bus services without installing a service file) then the prefix of the D-Bus name should match the application ID.
		`- * If the application is already packaged on https://flathub.org[Flathub] please use the same application ID.`
		- * Otherwise, you need to make up an application ID. This should be your best possible guess as to what the upstream would use - if they have their own domain name, that should be the basis, otherwise base it on the hosting - e.g. `com.github.<user/organization>.<Application>`. Note that the original idea of an application ID is that it is in a reversed name that is under your control, so if possible, please coordinate with the upstream, ask them if your choice is OK, and ask them to rename their desktop file and icon to match that.

		`- Applications can only export resources under their application ID, so the desktop file and icon for the application need the appropriate name. The best place to implement this is upstream. The second best place is in the Fedora application package. But if this isn’t possible, you can do this in your container.yaml. See the <<Renames>> section below.`
		`+ * If the application exports any D-Bus services`
		+ (Look for files in `/usr/share/dbus-1/services/` —
		`+ though an application can export D-Bus services without installing a service file)`
		`+ then the prefix of the D-Bus name should match the application ID.`
		`+`
		`+ * If the application is already packaged on https://flathub.org[Flathub]`
		`+ please use the same application ID.`
		`+`
		`+ * Otherwise, you need to make up an application ID.`
		`+ This should be your best possible guess as to what the upstream would use —`
		`+ if they have their own domain name, that should be the basis,`
		+ otherwise base it on the hosting — e.g. `com.github.<user/organization>.<Application>`.
		`+ Note that the original idea of an application ID is that it is in a reversed name that is under your control,`
		`+ so if possible, please coordinate with the upstream,`
		`+ ask them if your choice is OK,`
		`+ and ask them to rename their desktop file and icon to match that.`
		`+`
		`+ Applications can only export resources under their application ID,`
		`+ so the desktop file and icon for the application need the appropriate name.`
		`+ The best place to implement this is upstream.`
		`+ The second best place is in the Fedora application package.`
		`+ But if this isn’t possible, you can do this in your container.yaml.`
		`+ See the <<Renames>> section below.`

		`== Versioning`
		`- Flatpaks in Fedora are different from packages in that there isn’t a separate application version for F{PREVIOUSOSVER}, F{MAJOROSVER}, rawhide, etc. Instead there is a single version that is the latest stable version for all versions of Fedora.`
		`-`
		- A flatpak targets a particular runtime. Your stable version should ideally target the runtime corresponding to the latest released version of Fedora. If the released upstream stable version of the application has dependencies that are not available in a released version of Fedora and that can’t be bundled in your application module (e.g. it requires a newer version of the C compiler) then it’s acceptable to use the next version of the Fedora runtime, but this should be an unusual case. Your application might be based on the `flatpak-runtime:f{NEXTOSVER}` module, for example.
		`-`
		`- The module and container versions for your stable release should be in the stable branch of your git repository, and the stream of the module will be the stable stream.`
		`+ Flatpaks in Fedora are different from packages`
		`+ in that there isn’t a separate application version for F{PREVIOUSOSVER}, F{MAJOROSVER}, rawhide, etc.`
		`+ Instead there is a single version that is the latest stable version for all versions of Fedora.`
		`+`
		`+ A flatpak targets a particular runtime.`
		`+ Your stable version should ideally target the runtime corresponding to the latest released version of Fedora.`
		`+ If the released upstream stable version of the application has dependencies that are not available in a released version of Fedora`
		`+ and that can’t be bundled in your application module`
		`+ (e.g. it requires a newer version of the C compiler)`
		`+ then it’s acceptable to use the next version of the Fedora runtime,`
		`+ but this should be an unusual case.`
		+ Your application might be based on the `flatpak-runtime:f{NEXTOSVER}` module, for example.
		`+`
		`+ The module and container versions for your stable release should be in the stable branch of your git repository,`
		`+ and the stream of the module will be the stable stream.`

		== `<application>.yaml`

		`@@ -69,11 +99,13 @@`
		`--env=DCONF_USER_CONFIG_DIR=.config/dconf`
		`----`

		`- See http://docs.flatpak.org/en/latest/sandbox-permissions-reference.html and the flatpak-build(1) manual page.`
		`+ See http://docs.flatpak.org/en/latest/sandbox-permissions-reference.html`
		`+ and the flatpak-build(1) manual page.`

		`=== Renames`
		`- Many existing applications in Fedora do not have an application in standard form. You can add keys to your`
		`- container.yaml to rename exported resources to match the application ID.`
		`+ Many existing applications in Fedora do not have an application in standard form.`
		`+ You can add keys to your container.yaml`
		`+ to rename exported resources to match the application ID.`

		`....`
		`flatpak:`
		`@@ -82,12 +114,14 @@`
		`rename-icon: eog`
		`....`

		`- The preferred way, however, is to fix the application ID in the RPM packaging, or even better, upstream.`
		`+ The preferred way, however, is to fix the application ID in the RPM packaging,`
		`+ or even better, upstream.`
		`The reason this is better is that the system can understand the relationship between the two applications,`
		`and won't show duplicate entries in GNOME Software or the installed application list.`

		`=== Other keys`
		- The complete list of supported keys from the Flatpak builder manifest file that you can add to the `flatpak:` section of `container.yaml` is:
		`+ The complete list of supported keys from the Flatpak builder manifest file`
		+ that you can add to the `flatpak:` section of `container.yaml` is:

		* `appdata-license`
		* `appstream-compose`

modules/ROOT/pages/index.adoc

file modified

+11 -3

		`@@ -1,8 +1,16 @@`
		`= Flatpak`

		`- https://flatpak.org[Flatpaks] are a new way of deploying applications. If you have an application already packaged as a Fedora package, creating Flatpak offers a number of advantages:`
		`+ https://flatpak.org[Flatpaks] are a new way of deploying applications.`
		`+ If you have an application already packaged as a Fedora package,`
		`+ creating Flatpak offers a number of advantages:`
		`+`
		`+ * The application can be safely updated without rebooting the system`
		`+ (you can update a package without rebooting your system using dnf from the command line, of course,`
		`+ but GNOME Software only offers updating applications as part of an offline system update.)`

		`- * The application can be safely updated without rebooting the system (you can update a package without rebooting your system using dnf from the command line, of course, but GNOME Software only offers updating applications as part of an offline system update.)`
		`* The application can seamlessly be installed on Fedora Silverblue`
		`- * The Flatpak works across all supported Fedora versions - you don’t have to update trailing versions of Fedora for people to use the newest application version.`
		`+`
		`+ * The Flatpak works across all supported Fedora versions —`
		`+ you don’t have to update trailing versions of Fedora for people to use the newest application version.`
		`+`
		`* The Flatpak can be run by people running on other distributions`

modules/ROOT/pages/runtimes.adoc

file modified

+47 -48

		`@@ -1,63 +1,62 @@`
		`= Packaging Runtimes`

		`- As we've seen, each Flatpak targets a particular runtime, which provides`
		- shared binaries, libraries, and data files, and is mounted at `/usr` when the
		`- Flatpak is run.`
		`-`
		- All Flatpaks in Fedora target the `org.fedora.Platform` runtime. Using
		`- a single runtime simplifies maintenance and avoids users having to`
		`- download multiple runtimes. In general, you will not need to modify`
		`- this runtime when creating an application, since any additional`
		`- packages you need will be bundled with the application. However, if`
		`- you find a bug in the runtime and want to help fix it, or want to help`
		`- participate in maintainance of the Fedora runtimes, then it's useful`
		`- to know how runtimes are built.`
		`-`
		- In addition to the `org.fedora.Platform`, three other runtimes are built in
		`- Fedora infrastructure`
		`+ As we've seen, each Flatpak targets a particular runtime,`
		`+ which provides shared binaries, libraries, and data files,`
		+ and is mounted at `/usr` when the Flatpak is run.
		`+`
		+ All Flatpaks in Fedora target the `org.fedora.Platform` runtime.
		`+ Using a single runtime simplifies maintenance`
		`+ and avoids users having to download multiple runtimes.`
		`+ In general, you will not need to modify this runtime when creating an application,`
		`+ since any additional packages you need will be bundled with the application.`
		`+ However, if you find a bug in the runtime and want to help fix it,`
		`+ or want to help participate in maintainance of the Fedora runtimes,`
		`+ then it's useful to know how runtimes are built.`
		`+`
		+ In addition to the `org.fedora.Platform`,
		`+ three other runtimes are built in Fedora infrastructure`

		`org.fedoraproject.Sdk`::
		- This is a SDK that extends `org.fedora.Platform` with compilers and header
		`- files to enable building applications against it using the flatpak-builder`
		`- tool.`
		+ This is a SDK that extends `org.fedora.Platform` with compilers and header files
		`+ to enable building applications against it using the flatpak-builder ool.`
		`org.fedoraproject.BasePlatform`::
		- This is a smaller runtime. It is similar to the upstream `org.freedesktop`
		`- runtime. The idea of this runtime is that it establishes a package set`
		`- that can be carried over into an enterprise-linux runtime that will`
		`- have long-term support and stability.`
		`+ This is a smaller runtime.`
		+ It is similar to the upstream `org.freedesktop` runtime.
		`+ The idea of this runtime is that it establishes a package set`
		`+ that can be carried over into an enterprise-linux runtime`
		`+ that will have long-term support and stability.`
		`org.fedoraproject.BaseSdk`::
		The SDK corresponding to `org.fedoraproject.BasePlatform`

		`- Runtimes are defined in a similar way to Flatpaks. The content of the runtimes`
		`- is defined in the https://src.fedoraproject.org/modules/flatpak-runtime[flatpak-runtime module].`
		`- The different profiles of the module define the different`
		`- runtimes.`
		`+ Runtimes are defined in a similar way to Flatpaks.`
		`+ The content of the runtimes is defined in the`
		`+ https://src.fedoraproject.org/modules/flatpak-runtime[flatpak-runtime module].`
		`+ The different profiles of the module define the different runtimes.`

		`- WARNING: the following describes the way things will be organized. Currently, only`
		`- the main flatpak-runtime is built, and defined directly in`
		`+ WARNING: the following describes the way things will be organized.`
		`+ Currently, only the main flatpak-runtime is built, and defined directly in`
		https://src.fedoraproject.org/modules/flatpak-runtime[`modules/flatpak-runtime`]

		`- Then the runtimes are built into containers - but since`
		`- there are multiple containers built for the same runtime, the`
		`- simplification of having both the module and container definition in a`
		`- single git repository doesn't work. Instead the container definitions`
		`- are found in separate git repositories:`
		`+ Then the runtimes are built into containers —`
		`+ but since there are multiple containers built for the same runtime,`
		`+ the simplification of having both the module and container definition in a single git repository doesn't work.`
		`+ Instead the container definitions are found in separate git repositories:`
		https://src.fedoraproject.org/flatpaks/flatpak-runtime[`flatpaks/flatpak-runtime`].
		https://src.fedoraproject.org/flatpaks/flatpak-sdk[`flatpaks/flatpak-sdk`].
		https://src.fedoraproject.org/flatpaks/flatpak-base-runtime[`flatpaks/flatpak-base-runtime`].
		https://src.fedoraproject.org/flatpaks/flatpak-base-sdk[`flatpaks/flatpak-base-sdk`].
		`- These git repositories must be kept tightly in sync with the runtime module, but don't need`
		`- to be modified very often.`
		`-`
		- The package lists in `flatpak-runtime.yaml` are maintained with scripts that
		`- is also found in the flatpak-runtime module. The idea is that the contents of the`
		- runtime should be a superset of the `org.gnome.Platform` runtime, with the addition
		`- of libraries that are frequently used by popular non-GNOME applications, such as`
		`- qt5 and SDL. For more information about the maintenance scripts, see the`
		`- https://src.fedoraproject.org/modules/flatpak-runtime[README.md]`
		`- in the module.`
		`-`
		- The module definition for `flatpak-runtime` has an xmd section that includes
		`- extra information that is used at application build time to allow the resulting`
		`- Flatpak to automatically depend on the right runtime and version without requiring`
		`- it to be separately specified.`
		`+ These git repositories must be kept tightly in sync with the runtime module,`
		`+ but don't need to be modified very often.`
		`+`
		+ The package lists in `flatpak-runtime.yaml` are maintained with scripts
		`+ that is also found in the flatpak-runtime module.`
		+ The idea is that the contents of the runtime should be a superset of the `org.gnome.Platform` runtime,
		`+ with the addition of libraries that are frequently used by popular non-GNOME applications,`
		`+ such as qt5 and SDL.`
		`+ For more information about the maintenance scripts,`
		`+ see the https://src.fedoraproject.org/modules/flatpak-runtime[README.md] in the module.`
		`+`
		+ The module definition for `flatpak-runtime` has an xmd section
		`+ that includes extra information that is used at application build time`
		`+ to allow the resulting Flatpak to automatically depend on the right runtime and version`
		`+ without requiring it to be separately specified.`

modules/ROOT/pages/troubleshooting.adoc

file modified

+43 -30

		`@@ -5,12 +5,16 @@`
		`== Module build problems`

		`== Rebuilding a module against a local component`
		`- If you find a build problem with a component in your module, you'll want to build`
		`- the module using a local git checkout for the module, so you can put fixes in there:`
		`+ If you find a build problem with a component in your module,`
		`+ you'll want to build the module using a local git checkout for the module,`
		`+ so you can put fixes in there:`

		* Checkout the module from dist-git using `fedpkg clone` as a subdirectory of `<path to checkouts>`
		`+`
		`* Unless you are using https://github.com/owtaylor/fedora-packager-container[fedora-packager-container],`
		- edit your `/etc/module-build-service/config.py` (create the file if it doesn't exist) so it contains the following:
		+ edit your `/etc/module-build-service/config.py`
		`+ (create the file if it doesn't exist)`
		`+ so it contains the following:`

		`....`
		`from copy import deepcopy`
		`@@ -29,7 +33,10 @@`
		`}`
		`....`

		- * As more and more modules are being limited to build just on the supported architectures (`aarch64` and `x86_64` to save Fedora resources) you will need https://pagure.io/fm-orchestrator/pull-request/1747[fm-orchestrator#1747] applied locally, otherwise the build will fail.
		`+ * As more and more modules are being limited to build just on the supported architectures`
		+ (`aarch64` and `x86_64` to save Fedora resources)
		`+ you will need https://pagure.io/fm-orchestrator/pull-request/1747[fm-orchestrator#1747] applied locally,`
		`+ otherwise the build will fail.`

		* Edit your `<application>.yaml` and add a repository line:

		`@@ -42,12 +49,17 @@`
		`ref: f{MAJOROSVER}`
		`----`

		- * Use `fedpkg switch-branch` to switch to the rfe from `<application.yaml>` (or change the `ref:` in `<application.yaml`> to be `rawhide`)
		- * Make your changes, commit them and make sure that sources are downloaded with `fedpkg sources`
		+ * Use `fedpkg switch-branch` to switch to the rfe from `<application.yaml>`
		+ (or change the `ref:` in `<application.yaml`> to be `rawhide`)
		`+`
		`+ * Make your changes, commit them`
		+ and make sure that sources are downloaded with `fedpkg sources`
		`+`
		`* Try building your module again`

		`=== Quickly debugging prefix=/app builds`
		- If you hit a problem where a component fails to build with `prefix=/app` and you need to debug in detail,
		+ If you hit a problem where a component fails to build with `prefix=/app`
		`+ and you need to debug in detail,`
		`as a shortcut, you can temporarily do the following:`

		`[subs="attributes+"]`
		`@@ -62,15 +74,17 @@`

		=== Files outside of `/app`

		`- The most common reason for a packaging failing to build is that some file in the`
		- package is installed with a hard-coded path of `/usr` rather than respecting the
		- macros such as `+%{_prefix}+`, `+%{_libdir}+`, etc. This might require adjustment
		`- of the spec file, passing additional variables into the make command, or in rare`
		`- cases, patching the Makefiles.`
		`+ The most common reason for a packaging failing to build`
		+ is that some file in the package is installed with a hard-coded path of `/usr`
		+ rather than respecting the macros such as `+%{_prefix}+`, `+%{_libdir}+`, etc.
		`+ This might require adjustment of the spec file,`
		`+ passing additional variables into the make command,`
		`+ or in rare cases, patching the Makefiles.`

		`=== Uncompressed manual pages`
		`Currently, the RPM scripts that compress manual pages don't compress manual pages`
		- in `/app`. So if an RPM has
		+ in `/app`.
		`+ So if an RPM has`

		`....`
		`%files`
		`@@ -78,31 +92,30 @@`
		`%{_mandir}/man1/<command>.1.gz`
		`....`

		`- It will fail to build in a Flatpak module. The recommendation in the Fedora packaging`
		`- guidelines is to have:`
		`+ It will fail to build in a Flatpak module.`
		`+ The recommendation in the Fedora packaging guidelines is to have:`
		`....`
		`%{_mandir}/man1/<command>.1*`
		`....`

		`- which is more robust against future changes to the RPM scripts to use different`
		`- compression.`
		`+ which is more robust against future changes to the RPM scripts to use different compression.`

		`== Container build problems`

		`=== Package installation failures`
		`- During installation of packages to build a Flatpak container, the set of packages is`
		`- restricted to packages in the runtime and packages built in your module. Other packages`
		`- in Fedora will be ignored. If you see a message about missing dependencies that`
		`- you know are in Fedora, this is because they are being ignored because of this`
		`- restriction.`
		`-`
		- `fedmod rpm2flatpak` should have added all necessary dependencies not
		`- in the runtime to your module. However, subsequent packaging changes`
		`- might require updates to your module.`
		`-`
		`- You could also see failures if a package in the runtime grew a new dependency.and the`
		`- runtime hasn't been updated. If the package with the dependency causing the dnf failure`
		`- isn't part of your module, please bug an issue against`
		`+ During installation of packages to build a Flatpak container,`
		`+ the set of packages is restricted to packages in the runtime`
		`+ and packages built in your module.`
		`+ Other packages in Fedora will be ignored.`
		`+ If you see a message about missing dependencies that you know are in Fedora,`
		`+ this is because they are being ignored because of this restriction.`
		`+`
		+ `fedmod rpm2flatpak` should have added all necessary dependencies not in the runtime to your module. However, subsequent packaging changes might require updates to your module.
		`+`
		`+ You could also see failures if a package in the runtime grew a new dependency,`
		`+ and the runtime hasn't been updated.`
		`+ If the package with the dependency causing the dnf failure isn't part of your module,`
		`+ please bug an issue against`
		`https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora%20Modules&component=flatpak-runtime[flatpak-runtime].`

		`// == Problems running applications`

modules/ROOT/pages/tutorial.adoc

file modified

+33 -10

		`@@ -3,9 +3,21 @@`

		`= Packaging Tutorial`

		`- Creating a Flatpak of an application that is already packaged in Fedora involves two steps. First you need to create a module for the application. This module will be used to rebuild the application RPM and RPMs. Then you need to create a container out of the module. In the Fedora context, flatpaks are just another form of container, and are handled very similar to the Docker containers used for server applications.`
		`-`
		- Just as for packages, the instructions for building modules and containers are stored in git on https://src.fedoraproject.org and builds are coordinated by https://koji.fedoraproject.org. The flatpak for a an application can be found on https://src.fedoraproject.org in the repository `flatpaks/<application>`; this git repository contains two files: `<application>.yaml`, which defines the contents of the module, and `container.yaml`, which defines how the module is turned into a Flatpak container.
		`+ Creating a Flatpak of an application that is already packaged in Fedora involves two steps.`
		`+ First you need to create a module for the application.`
		`+ This module will be used to rebuild the application RPM and RPMs.`
		`+ Then you need to create a container out of the module.`
		`+ In the Fedora context, flatpaks are just another form of container,`
		`+ and are handled very similar to the Docker containers used for server applications.`
		`+`
		`+ Just as for packages,`
		`+ the instructions for building modules and containers are stored in git on https://src.fedoraproject.org`
		`+ and builds are coordinated by https://koji.fedoraproject.org.`
		`+ The flatpak for a an application can be found on https://src.fedoraproject.org`
		+ in the repository `flatpaks/<application>`;
		`+ this git repository contains two files:`
		+ `<application>.yaml`, which defines the contents of the module,
		+ and `container.yaml`, which defines how the module is turned into a Flatpak container.

		`== Setup`

		`@@ -13,7 +25,9 @@`

		`$ sudo dnf install flatpak-module-tools fedmod`

		- Make sure that your user is in the `mock` group (both local module builds and local container builds use https://github.com/rpm-software-management/mock/wiki[mock]).
		+ Make sure that your user is in the `mock` group
		`+ (both local module builds and local container builds use`
		`+ https://github.com/rpm-software-management/mock/wiki[mock]).`

		`$ sudo usermod -a -G mock $USER`

		`@@ -105,11 +119,13 @@`
		`<1> Source and description come from RPM metadata`
		`<2> The default profile lists RPMs to be included along with their dependencies`
		`<3> The main package for the application`
		`- <4> This is the branch of the RPM in https://src.fedoraproject.org to use for this component. You can use any branch, or even point to a specific commit.`
		`+ <4> This is the branch of the RPM in https://src.fedoraproject.org to use for this component.`
		`+ You can use any branch, or even point to a specific commit.`
		`<5> Further source rpms that will be rebuilt for bundling`

		`- This could be used as-is. For more complex cases, it may be necessary to add additional`
		- `buildorder:` keys so that the bundle dependencies build in the correct order.
		`+ This could be used as-is.`
		+ For more complex cases, it may be necessary to add additional `buildorder:` keys
		`+ so that the bundle dependencies build in the correct order.`

		Then we'll look at the `container.yaml` file.

		`@@ -205,6 +221,13 @@`
		`$ flatpak-module install --koji <application>:stable`

		`== Creating an update`
		- Find the NVR of your Flatpak build - if you don’t have it in your terminal scrollback go to https://koji.fedoraproject.org/ and search in "Packages" for the application name. The build ID for the _Flatpak_ build will be something like: `myapplication-20b180601144429.2`.
		`-`
		`- Go to https://bodhi.fedoraproject.org/updates/new and enter the flatpak NVR under Candidate Builds (ignore “Packages”). Enter text under “Update notes” like “Initial Flatpak of <application>”, and hit <Submit>.`
		`+ Find the NVR of your Flatpak build —`
		`+ if you don’t have it in your terminal scrollback go to https://koji.fedoraproject.org/`
		`+ and search in "Packages" for the application name.`
		`+ The build ID for the _Flatpak_ build will be something like:`
		+ `myapplication-20b180601144429.2`.
		`+`
		`+ Go to https://bodhi.fedoraproject.org/updates/new`
		`+ and enter the flatpak NVR under Candidate Builds (ignore “Packages”).`
		`+ Enter text under “Update notes” like “Initial Flatpak of <application>”,`
		`+ and hit <Submit>.`

oturpe commented a year ago

Based on discussion at #16.
No other changes than changing linebreaks is included.

kalev commented a year ago

I've never seen semantic line breaks before. To me it feels like it makes it harder to read the text and work with it, but perhaps it's worth it due to how it makes diffs nicer.

I'll leave it up to the docs team to merge this one if they prefer it that way :)

Thanks for helping out with the flatpak docs!

jibecfed commented a year ago

When it is full stop/period, I feel like this way to use linebreaks makes sense to make it easier to read and edit.
But for commas, this looks a little bit artificial to me, text editors will handle long sentences anyway.

Whatever you decides, I suggest to make sure text is correctly aligned in lists:

* This is first sentence.
This is a second sentence, with a wrong alignment.
* This is a third sentence.
  This is a fourth sentence, with a good alignment.

oturpe commented a year ago

Hello all,

I looks like the buy-in for semantic line breaks is weaker than I understood from the discussion in #16.
I can do the changes proposed by @jibecfed —
I have also noticed that when I write, my "semantic lines" are getting longer,
so if you want clear rules, the principle of breaking at full stop seems reasonable.

Please first indicate that after making the requested changes, you will merge this.
That way, my work won't go to waste if you do not actually want semantic linebreaks here.

To explain the reasoning for semantic linebreaks,
Pagure's web UI's diff viewer is really terrible with long lines, because it does not do line wrapping.
For example, the Packaging Guidelines page is the largest and most complex piece of Fedora docs,
and receives many contributions.
It is quite common to see pull requests having trouble getting reviewed there.
The reviewers simply cannot understand what has changed in long lines, such as single-line paragraphs.
Semantic linebreaks is really the best solution for this problem,
and their value does not completely disappear even if a better diff viewer becomes available later.

Edited a year ago by oturpe

rebased onto 5f66937

a year ago

oturpe commented a year ago

Closing as stale.

Pull-Request has been closed by oturpe

a year ago