From 54503a603a6790b7897515f43931ae9fd4522230 Mon Sep 17 00:00:00 2001
From: Fabio Valentini <decathorpe@gmail.com>
Date: Jul 01 2022 18:39:06 +0000
Subject: [PATCH 1/2] Java: reformat long lines, fix minor grammar, clean up punctuation


---

diff --git a/guidelines/modules/ROOT/pages/Java.adoc b/guidelines/modules/ROOT/pages/Java.adoc
index 6d0aba1..df4e5e5 100644
--- a/guidelines/modules/ROOT/pages/Java.adoc
+++ b/guidelines/modules/ROOT/pages/Java.adoc
@@ -1,9 +1,23 @@
 = Java Packaging Guidelines
+:last-reviewed: 2022-07-01
 :toc:
 
-This page represents Fedora guidelines for packaging libraries and applications written in Java and related languages using Java Virtual Machine as bytecode interpreter. It does not aim to extensively describe packaging techniques and tips. RPM macros and commands used here are documented in man pages. Furthermore a separate https://fedora-java.github.io/howto/latest/[Java Packaging HOWTO] describes Java packaging techniques in detail and includes examples, templates and documentation aimed at packagers and Java developers who are taking their first steps in Java RPM packaging.
+This page represents Fedora guidelines
+for packaging libraries and applications
+written in Java and related languages
+that use the Java Virtual Machine as a bytecode interpreter.
 
-Fedora Java packaging is originally based on https://web.archive.org/web/20191223234327/http://www.jpackage.org/[JPackage Project] standards. Over time we have diverged in packaging tools in most areas but we mostly keep backward compatibility with older packages that make use of JPackage standards.
+It does not aim to extensively describe packaging techniques and tips.
+RPM macros and commands used here are documented in man pages.
+Furthermore, a separate https://fedora-java.github.io/howto/latest/[Java Packaging HOWTO]
+describes Java packaging techniques in detail
+and includes examples, templates and documentation aimed at packagers and Java developers
+who are taking their first steps in Java RPM packaging.
+
+Fedora Java packaging is originally based on the https://web.archive.org/web/20191223234327/http://www.jpackage.org/[JPackage Project] standards.
+Over time, we have diverged in packaging tools in most areas
+but we mostly keep backward compatibility with older packages
+that make use of JPackage standards.
 
 == Package naming
 
@@ -19,28 +33,34 @@ Packages MUST follow the standard Fedora xref:Versioning.adoc[package versioning
 
 Packages MUST follow the standard Fedora xref:what-can-be-packaged.adoc#prebuilt-binaries-or-libraries[dependency bundling guidelines].
 
-In particular `+*.class+` and `+*.jar+` files from upstream releases MUST NOT be used during build of Fedora packages and they MUST NOT be included in binary RPM.
+In particular, `+*.class+` and `+*.jar+` files from upstream releases
+MUST NOT be used during build of Fedora packages
+and they MUST NOT be included in binary RPM.
 
 == JAR file installation
 
-The following applies to all JAR files except <<JNI,JNI-using JAR files>> and application-specific JAR files (i.e., JAR files that can only reasonably be used as part of an application and therefore constitute application-private data).
+The following applies to all JAR files
+except <<JNI,JNI-using JAR files>> and application-specific JAR files
+(i.e., JAR files that can only reasonably be used as part of an application
+and therefore constitute application-private data).
 
 === Split JAR files
 
-If a project offers the choice of packaging it as a single monolithic JAR or several ones, the split packaging SHOULD be preferred.
+If a project offers the choice of packaging it
+as a single monolithic JAR or as several separate JARs,
+the split packaging SHOULD be preferred.
 
 === Installation directory
 
 * All architecture-independent JAR files MUST go into `+%{_javadir}+` or its subdirectory.
-
 * For installation of architecture dependent JAR files, see <<JNI>>.
 
 === Filenames
 
 * If the package provides a *single* JAR file installed filename SHOULD be `+%{name}.jar+`.
-* If the package provides *multiple* JAR files, they SHOULD be installed in a `+%{name}+` subdirectory
-* Versioned JAR files (`+*-%{version}.jar+`) MUST NOT be installed unless the package is a compatibility package
-* Packages MAY provide alternative filenames as long as they do not conflict with other packages
+* If the package provides *multiple* JAR files, they SHOULD be installed in a `+%{name}+` subdirectory.
+* Versioned JAR files (`+*-%{version}.jar+`) MUST NOT be installed unless the package is a compatibility package.
+* Packages MAY provide alternative filenames, as long as they do not conflict with other packages.
 
 == BuildRequires and Requires
 
@@ -50,58 +70,87 @@ Java packages MUST BuildRequire their respective build system:
 * `+BuildRequires: ant+` for packages built with ant
 * `+BuildRequires: java-devel+` for packages built with javac
 
-Java binary packages or their dependencies MUST have Requires (generated by RPM or manual) on:
+Java binary packages or their dependencies MUST have `+Requires+` (generated by RPM or manual) on:
 
 * `+java-headless+` or `+java-headless >= 1:minimal_required_version+`
 * `+javapackages-filesystem+`
 
-If java-headless requirement is insufficient package MUST have Requires:
-
-* `+java+` or `+java >= 1:minimal_required_version+`
+If a `+java-headless+` requirement is insufficient,
+then the package MUST have `+Requires+` for
+`+java+` or `+java >= 1:minimal_required_version+`.
 
 == Javadoc installation
 
-* javadoc documentation MAY be generated
-* If javadoc documentation is generated it MUST be installed into a directory of `+%{_javadocdir}/%{name}+` as part of javadoc subpackage
+* JavaDoc documentation MAY be generated.
+* If javadoc documentation is generated,
+  it MUST be installed into a directory of `+%{_javadocdir}/%{name}+`
+  as part of the `+-javadoc+` subpackage.
 * Directory or symlink `+%{_javadocdir}/%{name}-%{version}+` SHOULD NOT exist.
-* The javadoc subpackage MUST be declared `+noarch+` even if main package is architecture specific.
+* The javadoc subpackage MUST be declared `+noarch+`, even if main package is architecture specific.
 
 == No class-path in MANIFEST.MF
 
-* JAR files MUST NOT include `+class-path+` entry inside META-INF/MANIFEST.MF
+JAR files MUST NOT include a `+class-path+` entry
+in their `+META-INF/MANIFEST.MF+` file.
 
 == Hardcoded paths
 
-Packages MUST NOT hardcode paths to JAR files they use. When package needs to reference a JAR file, packager SHOULD use one of tools designed to locating JAR files in the system.
+Packages MUST NOT hardcode paths to JAR files they use.
+When a package needs to reference a JAR file,
+the packager SHOULD use one of tools
+that are designed for locating JAR files in the system.
 
 == Maven pom.xml files
 
-If upstream project is shipping Maven `+pom.xml+` files, these MUST be installed. Additionally package MUST install mapping between upstream artifact and filesystem by using the `+%mvn_install+` macro.
+If upstream project is shipping Maven `+pom.xml+` files,
+these MUST be installed.
+Additionally, the package MUST install a mapping between the upstream artifact
+and the filesystem by using the `+%mvn_install+` macro.
 
-If upstream project does not ship Maven `+pom.xml+` file, official https://mvnrepository.com/[maven repository] should be searched and if there are `+pom.xml+` files they SHOULD be installed.
+If upstream project does not ship Maven `+pom.xml+` file,
+the official https://mvnrepository.com/[maven repository] should be consulted
+and if the project publishes `+pom.xml+` files there,
+they SHOULD be included.
 
-If modifications to Maven pom.xml files are needed `+%pom_*+` family of macros SHOULD be used
+If modifications to Maven pom.xml files are needed,
+the `+%pom_*+` family of macros SHOULD be used.
 
 == Wrapper Scripts
 
-Applications wishing to provide a convenient method of execution SHOULD provide a wrapper script in `+%{_bindir}+`. Packages SHOULD use `+%jpackage_script+` to create these wrapper scripts.
+Applications wishing to provide a convenient method of execution
+SHOULD provide a wrapper script in `+%{_bindir}+`.
+Packages SHOULD use `+%jpackage_script+` to create these wrapper scripts.
 
 == Compatibility packages
 
-In certain cases it might be necessary to create compatibility packages that provide older API/ABI level of the same library. However creating these compatibility packages is strongly discouraged. To standardize and simplify packaging of such compatibility packages following rules apply:
+In certain cases it might be necessary to create compatibility packages
+that provide older API/ABI level of the same library.
+However, creating these compatibility packages is strongly discouraged.
 
-* Compatibility packages MUST be named in the same way as original except addition of version to package name,
-* Any JAR and POM files MUST be versioned.
+To standardize and simplify packaging of such compatibility packages,
+the following rules apply:
+
+* Compatibility packages MUST be named in the same way as the original package
+  except the addition of the version to the package's name.
+* Any JAR and POM files MUST be versioned, as well.
 
 [#JNI]
 == Packaging JAR files that use JNI
 
 === Applicability
 
-Java programs that wish to make calls into native libraries do so via the Java Native Interface (JNI). A Java package uses JNI if it contains a .so file. Note that this file can be embedded within JAR files themselves.
+Java programs that wish to make calls into native libraries
+do so via the Java Native Interface (JNI).
+A Java package uses JNI if it contains a .so file.
+Note that this file can be embedded within JAR files themselves.
 
 === Guideline
 
-* JNI packages MUST follow guidelines of ordinary Java packages with exceptions listed here
-* JAR files using JNI or containing JNI shared objects themselves MUST be placed in `+%{_jnidir}+` and MAY be symlinked to `+%{_libdir}/%{name}+`.
-* JNI shared objects MUST be placed in `+%{_libdir}/%{name}+`
+JNI packages MUST follow guidelines of ordinary Java packages,
+with these exceptions:
+
+* JAR files using JNI or containing JNI shared objects themselves
+  MUST be placed in `+%{_jnidir}+`,
+  but MAY be symlinked to `+%{_libdir}/%{name}+`.
+* JNI shared objects MUST be placed in `+%{_libdir}/%{name}+`.
+

From fc365b475a71be716d07e0891cf11ead8e8b8a5c Mon Sep 17 00:00:00 2001
From: Fabio Valentini <decathorpe@gmail.com>
Date: Jul 01 2022 18:39:06 +0000
Subject: [PATCH 2/2] Java: document %{java_arches} macro


---

diff --git a/guidelines/modules/ROOT/pages/Java.adoc b/guidelines/modules/ROOT/pages/Java.adoc
index df4e5e5..ceec760 100644
--- a/guidelines/modules/ROOT/pages/Java.adoc
+++ b/guidelines/modules/ROOT/pages/Java.adoc
@@ -29,6 +29,21 @@ Java API documentation MUST be placed into a sub-package called `+%{name}-javado
 
 Packages MUST follow the standard Fedora xref:Versioning.adoc[package versioning guidelines].
 
+== Architecture support
+
+The system JDK / JRE might not be available on all architectures
+that are supported by any given Fedora release.
+
+For this reason, all Java packages MUST contain an `+ExclusiveArch+` tag:
+
+* Packages that build only `+noarch+` sub-packages
+  MUST use `+ExclusiveArch: %{java_arches} noarch+`.
+* Packages that include architecture-dependent build artifacts (i.e. <<JNI>> modules)
+  MUST use `+ExclusiveArch: %{java_arches}+`.
+
+The `+%{java_arches}+` macro contains a list of all the architectures
+where the system JRE / JDK is available and is defined on all Fedora releases.
+
 == Pre-built dependencies
 
 Packages MUST follow the standard Fedora xref:what-can-be-packaged.adoc#prebuilt-binaries-or-libraries[dependency bundling guidelines].

