#24 apply Flock feedback
Merged 11 months ago by asamalik. Opened 11 months ago by asamalik.

file modified
+3 -4

@@ -5,12 +5,11 @@

  *** xref:architecture/consuming/dnf-behavior.adoc[DNF Behavior]

  * xref:making-modules.adoc[Making Modules]

  ** xref:making-modules/adding-new-modules.adoc[Adding New Modules]

- ** xref:making-modules/updating-modules.adoc[Updating Modules]

- ** xref:making-modules/inspecting-build-failures.adoc[Inspecting Build Failures]

- ** xref:making-modules/building-modules-locally.adoc[Building Modules Locally]

+ ** xref:making-modules/updating-modules.adoc[Updating Existing Modules]

  ** xref:making-modules/defining-modules.adoc[Defining Modules in modulemd]

  ** xref:making-modules/managing-defaults.adoc[Managing Defaults]

- ** xref:making-modules/naming-guidelines.adoc[Naming Guidelines]

+ ** xref:making-modules/inspecting-build-failures.adoc[Inspecting Build Failures]

+ ** xref:making-modules/building-modules-locally.adoc[Building Modules Locally]

  * xref:using-modules.adoc[Using Modules]

  * xref:community.adoc[Community]

  ** xref:community/teams.adoc[Teams and Working Groups]

@@ -1,29 +1,23 @@

- **Goal**: Get your packages built as a module.

- 

- === Steps:

- 

- 1. Submit a module build using fedpkg.

- 2. Make sure your build succeeded.

- 

- === Details:

+ With Modularity, you no longer build individual packages. Instead, you need to submit a module build.

  

  Module builds are triggered using `fedpkg` from whithin your dist-git repository.

  

- For example, to submit a build of the `nodejs:10` module, run:

- 

  ----

- $ fedpkg clone modules/nodejs

- $ cd nodejs

- $ git checkout 10

+ $ fedpkg clone modules/NAME

+ $ cd NAME

+ $ fedpkg switch-branch BRANCH

  $ fedpkg module-build

  ----

  

+ * `NAME` — name of the module

+ * `BRANCH` — name of the stream branch of the module

+ 

  NOTE: Please note the module build ID. You will need it to verify the build state. It also helps you in the next step.

  

- To watch the satate of your module build, run:

+ To watch the state of your module build, run:

  

  ----

  $ fedpkg module-build-watch BUILD_ID

  ----

  

- When the module is in a "ready" state, you can continue to the next step. 

\ No newline at end of file

+ When the module is in a "ready" state, the build has successfully completed. 

\ No newline at end of file

@@ -1,22 +1,13 @@

- **Goal**: Make your module go through Bodhi — the Fedora updates system.

+ To make your module available to users, submit submit as an update to https://bodhi.fedoraproject.org/[Fedora Bodhi]. Make sure you are logged in, and then click on Create / New Update at the top-right corner. Fill out the following fields:

  

- === Steps:

- 

- 1. Submit your module as an update in Bodhi.

- 2. Make sure your update has passed potential user testing.

- 

- === Details:

- 

- To submit your module as an update, go to https://bodhi.fedoraproject.org/[Fedora Bodhi]. Make sure you are logged in, and then click on Create / New Update at the top-right corner. Fill out the following fields:

- 

- * Candidate Builds: MODULE_BUILD_ID

+ * Candidate Builds: `MODULE_BUILD_ID`

  * Update notes: notes for the users

  * Final details: check what applies

  

- One way of geting the MODULE_BUILD_ID is running the same command as in the previous step:

+ One way of geting the `MODULE_BUILD_ID` is running the same command as in the previous step:

  

  ----

- $ fedpkg module-build-watch BUILD_ID

+ $ fedpkg module-build-info BUILD_ID

  ----

  

  and changing the "koji tag" value in the following way:

@@ -1,76 +1,96 @@

  = Adding new modules to Fedora

  

- This page will guide you through the whole process of adding a new module to Fedora. There is also an official https://fedoraproject.org/wiki/Modularity/Adding_New_Modules_and_Managing_Defaults[process for adding new modules] which will give you a summary of the major steps you need to undergo, and is the authoritative point of truth.

+ This page will guide you through the whole process of adding a new module to Fedora:

  

- == Step 1: Get your RPM packages in place

+ 1. **<<RPM Sources>>** — To `dist-git/rpms` using stream branches.

+ 2. **<<Module Definition>>** — To `dist-git/modules` using stream branches.

+ 3. **<<Module Build>>** — Module is built as a unit. No individual package builds are done.

+ 4. **<<Publishing the Module>>** — Submitting a Bodhi update.

  

- **Goal**: Get your RPM package(s) pushed into the Fedora Distribution Git (dist-git).

+ == RPM Sources

  

- === Workflow Summary:

+ For each package in your module, you need to have a Fedora Distribution Git (dist-git) **repository** under `dist-git/rpms` with apropriate **stream branch**. New packages need to go through a **package review**.

  

- 1. Create your new RPM package.

- 2. Submit your package for Fedora Review. (only for new packages)

- 3. Request a new repository and/or a branch in dist-git.

- 4. Push your package sources into dist-git.

+ === Repositories and Stream Branches — New packages

  

- === Details:

+ The https://fedoraproject.org/wiki/Package_Review_Process#Contributor[Fedora Package Review Process] covers all the steps you need to take, except for stream branches. For that, please continue below to Existing packages.

  

- When creating your new http://rpm.org/[RPM package], please make sure it complies with the https://fedoraproject.org/wiki/Packaging:Guidelines[Fedora Packaging Guidelines].

+ === Repositories and Stream Branches — Existing packages

+ Requesting new stream branches for existing packages is done with `fedpkg`, and it doesn't require a package review.

  

- NOTE: If you adding a new branch to an existing package, you can skip the review part and proceed to requesting a new branch.

+ To create a new branch for a package that shares a name with the module (e.g. "postgresql"), run the following command which will create the package stream branch as well as the module and its stream branch together:

  

- To learn about the Fedora review, requesting repositories and branches, and pushing sources to dist-git, please see the https://fedoraproject.org/wiki/Package_Review_Process#Contributor[Fedora Package Review Process]

+ ----

+ $ fedpkg request-branch --repo=NAME --sl rawhide:2020-12-01 BRANCH

+ ----

+ * `NAME` — name of the package and the module

+ * `BRANCH` — name of the stream branch of the package and the module

+ * `rawhide:2020-12-01` — expected end of life, must end with either `12-01` or `06-01` 

  

- == Step 2: Get your module definition in place

+ If this package does not share a name with the module (such as for dependencies), then only request the stream branch for this package:

  

- **Goal**: Get your module definition pushed into the Fedora Distribution Git (dist-git).

+ ----

+ $ fedpkg request-branch --repo=NAME --sl rawhide:2020-12-01 --no-auto-module BRANCH

+ ----

+ * `--no-auto-module` — Skip the creation of a module of the same name

  

- === Steps:

+ Creation of the module and its stream branches separately will be covered later.

  

- 1. Write a modulemd.

- 2. Request a new repository and/or a branch in dist-git.

- 3. Push your modulemd into dist-git.

+ === Importing the RPM sources into dist-git

  

- === Details:

+ The last thing to do is to import the RPM sources into dist-git. Please refer to the https://fedoraproject.org/wiki/New_package_process_for_existing_contributors[New package process for existing contributors

+ ] for the complete steps.

  

- Writing a modulemd is covered in detail in the xref:making-modules/defining-modules.adoc[Defining Modules in modulemd] section.

+ == Module Definition

  

- NOTE: Running the following `fedpkg` commands requires a ticket to be created at https://pagure.io/settings/token/new and saved in `\~/.config/rpkg/fedpkg.conf`

+ For your module definition, you also need to have a dist-git **repository**, this time under `dist-git/modules`, with apropriate **stream branch**.

  

- WARNING: Please remember that the name of your module will be the name of your repository. The same way, the stream name of your module will be the name of the branch. Both of these will be visible to users.

+ === Repositories and Stream Branches — New modules

  

- To request a new repository in dist-git, for example for a `nodejs` module, run:

+ To request a new module repository in dist-git run:

  

  ----

- $ fedpkg --module-name modules/nodejs request-repo --exception

+ $ fedpkg request-repo --namespace modules --exception NAME

+ $ fedpkg request-branch --namespace modules --repo NAME BRANCH

  ----

  

- And to request a new branch, for example for a `nodejs:10` module, run:

+ * `NAME` — name of the module

+ * `BRANCH` — name of the stream branch of the module

+ 

+ === Repositories and Stream Branches — Existing modules

+ 

+ to request a new stream branch, run:

  

  ----

- $ fedpkg --module-name modules/nodejs request-branch 10

+ $ fedpkg request-branch --namespace modules --repo NAME BRANCH

  ----

  

- To push your modulemd into dist-git, clone the dist-git repository, change to the correct branch, add your modulemd, and push it as you would in git.

+ * `NAME` — name of the module

+ * `BRANCH` — name of the stream branch of the module

  

- NOTE: Please make sure that the name of your modulemd file matches the name of the dist-git repository.

+ === Write and push the modulemd

  

- For example, to push the `nodejs:10` module definition, run:

+ Writing a modulemd is covered in detail in the xref:making-modules/defining-modules.adoc[Defining Modules in modulemd] section.

+ 

+ NOTE: The name of the modulemd must match the name of the repository. Remember to replace every `NAME` in the following example.

  

  ----

- $ fedpkg clone modules/nodejs

- $ cd nodejs

- $ git checkout 10

- $ vim nodejs.yaml

- $ git add nodejs.yaml

+ $ fedpkg clone modules/NAME

+ $ cd NAME

+ $ fedpkg switch-branch BRANCH

+ $ vim NAME.yaml

+ $ git add NAME.yaml

  $ git commit -m "add the initial modulemd"

  $ git push

  ----

  

- == Step 3: Build your module

+ * `NAME` — name of the module

+ * `BRANCH` — name of the stream branch of the module

+ 

+ == Module Build

  

  include::{partialsdir}/submit-module-build.adoc[]

  

- == Step 4: Make your module available to users

+ == Publishing the Module

  

  include::{partialsdir}/submit-module-update.adoc[] 

\ No newline at end of file

@@ -1,12 +1,80 @@

  = Defining modules in modulemd

  

- Modules are defined using a https://pagure.io/modulemd[modulemd file]. The definition includes the summary and description, list of source RPM packages, build information i.e. buildroot, and usage information i.e. installation profiles or licenses.

+ Simply put, a **https://github.com/fedora-modularity/libmodulemd/blob/master/spec.v2.yaml[modulemd] is a file that defines what packages get build for what releases**. It includes a summary and a description, a list of source RPM packages, build information i.e. build order and macros, and usage information i.e. installation profiles and licenses.

  

- This page will help you with writing a module definition from scratch. Even though this page is meant to be up-to-date, please make sure your module complies with the https://fedoraproject.org/wiki/Module:Guidelines[Fedora Packaging Guidelines for Modules] as it is the authoritative point of truth.

+ == A typical modulemd example

  

- This page includes the <<Common definitions>>, the <<Advanced definitions>>, examples of <<A minimal modulemd>>, and a <<Bonus: Converting modulemd v1 to v2>>.

+ A typical modulemd file looks similar to the following examples. Read on for more details about each part of the modulemd file.

  

- == Common definitions

+ Feel free to copy/paste this example when creating your new module.

+ 

+ [source,yaml]

+ ----

+ document: modulemd

+ version: 2

+ data:

+     # === Information about this module ==================================

+     # (Can be copied from the main RPM package, but doesn't need to be)

+     summary: An example module

+     description: >-

+         A module for the demonstration of the metadata format. Also,

+         the obligatory lorem ipsum dolor sit amet goes right here.

+     

+     # === License of this modulemd file ==================================

+     # (Package licenses will be added automatically by the build system)

+     license:

+         module: 

+             - MIT

+     

+     # === Modular dependencies ===========================================

+     # (For which Fedora releases to build?)

+     dependencies:

+       - buildrequires:

+             platform: [] # <- Build for all Fedora releases

+         requires:

+             platform: [] # <- Run on all Fedora releases

+     

+     # === Module API (optional, but encouraged) ==========================

+     # (Which packages are API-stable?)

+     api:

+         rpms:

+             - package-one        # <- Binary RPM package name

+             - package-one-extras # <- Binary RPM package name

+             - package-one-cli    # <- Binary RPM package name

+             - package-one-devel  # <- Binary RPM package name

+             - package-two        # <- Binary RPM package name

+     

+     # === Installation profiles (optional, but encouraged) ===============

+     # (Helping users with installation by providing pre-defined groups)

+     profiles:

+         default:  # <- Name of the profile

+             description: A standard installation.

+             rpms:

+                 - package-one         # <- Binary RPM package name

+                 - package-one-extras  # <- Binary RPM package name

+                 - package-two         # <- Binary RPM package name

+         cli:      # <- Name of the profile

+             description: A command-line client.

+             rpms:

+                 - package-one-cli     # <- Binary RPM package name

+     

+     # === Packages in this module ========================================

+     # (Referenced by their dist-git repo name + branch name)

+     components:

+         rpms:

+             first-package:  # <- Source RPM package name

+                 ref: 3.0    # <- Branch name in dist-git

+                 rationale: Provides the core functionality.

+             second-package: # <- Source RPM package name

+                 ref: latest # <- Branch name in dist-git

+                 rationale: Web UI for the first-package.

+ ----

+ 

+ == Common modulemd definitions

+ 

+ These are the common parts of a modulemd file, used in the example above. Advanced definitions, including a complex example of Module Stream Expansion (MSE), are towards the end of this page.

+ 

+ === Document header

  

  Every modulemd starts with these three lines:

  

@@ -20,9 +88,9 @@

  

  <1> All the following definitions go here, under _data_.

  

- === Information about your module

+ === Information about this module

  

- Tell users what this module represents by writing a summary and a description, and how can they use it by specifying a license.

+ Tell users what this module represents by writing a summary and a description.

  

  [source,yaml]

  ----

@@ -30,42 +98,28 @@

      description: >-  <1>

          A module for the demonstration of the metadata format. Also,

          the obligatory lorem ipsum dolor sit amet goes right here.

-     license:

-         module: 

-             - MIT  <2>

  ----

  

  <1> The `>-` means new line in YAML. Useful for longer blocks of text, such as the description!

  

- <2> A license for this modulemd file. Fedora content, such as SPEC files or patches not included upstream, uses the MIT license by default, unless the component packager declares otherwise. 

  

+ === License of this modulemd file

  

- === List the packages

- 

- To make your module useful, include some RPM packages in it. List all source RPM packages this module should include.

+ This is a license of this very modulemd file and it doesn't need to be modified.

+ The buildsystem adds licenses of all packages to this list automatically.

  

  [source,yaml]

  ----

-     components:

-         rpms:

-             first-package:  <1>

-                 rationale: Provides the core functionality.  <2>

-                 ref: 3.0  <3>

-             second-package:

-                 rationale: Web UI for the first-package.

-                 ref: stable

-             ...  <4>

+     license:

+         module: 

+             - MIT  <1>

  ----

  

- <1> Name of the package — maps to a DistGit repository name.

- 

- <2> The reason why is this package here. Mostly for humans.

- 

- <3> DistGit branch, tag, or a commit — so the right version of the package gets included.

+ <1> A license for this modulemd file. Fedora content, such as SPEC files or patches not included upstream, uses the MIT license by default, unless the component packager declares otherwise. 

  

- <4> List as many packages as you need.

+ === Modular dependencies

  

- === For which releases?

+ Simply put: For which Fedora releases to build?

  

  To build your module for all Fedora releases that are actively maintained, use the following definition. For anything more than this, such as building against other modules or requiring other modules during runtime, please see the Advanced section below.

  

@@ -78,7 +132,7 @@

              platform: []

  ----

  

- === Help users install it (optional, but encouraged)

+ === Installation profiles (optional, but encouraged)

  

  To help users install your module, define installation profiles. These profiles represent a specific use case of your module. Most modules have at least a default profile. But you can specify more. For example, a database module can have a server and a client profile.

  

@@ -106,7 +160,7 @@

  

  <4> List as many profiles as you need.

  

- === Public API (optional, but encouraged)

+ === Module API (optional, but encouraged)

  

  List all binary RPM packages in your module that you consider to be the main stable feature of the module. Other (unlisted) packages should be considered unsupported, or an implementation detail.

  

@@ -121,6 +175,31 @@

              - package-two

  ----

  

+ === Packages in this module

+ 

+ List all source SRPM packages this module should include, referenced them by their dist-git repo name + branch name.

+ 

+ [source,yaml]

+ ----

+     components:

+         rpms:

+             first-package:  <1>

+                 rationale: Provides the core functionality.  <2>

+                 ref: 3.0  <3>

+             second-package:

+                 rationale: Web UI for the first-package.

+                 ref: latest

+             ...  <4>

+ ----

+ 

+ <1> Name of the package — maps to a DistGit repository name.

+ 

+ <2> The reason why is this package here. Mostly for humans.

+ 

+ <3> DistGit branch, tag, or a commit — so the right version of the package gets included.

+ 

+ <4> List as many packages as you need.

+ 

  == Advanced definitions

  

  === References to the upstream (optional)

@@ -159,7 +238,7 @@

                  buildorder: 0  <1>

              second-package:

                  rationale: Web UI for the first-package.

-                 ref: stable

+                 ref: latest

                  buildorder: 10  <1>

  ----

  

@@ -187,10 +266,7 @@

  * built agains one or more streams of the same module

  * work with one or more streams of another module

  

- 

- ==== Building for a specific Fedora release(s) only

- 

- Building **only for Fedora 28**:

+ **Building only for Fedora 28**:

  

  [source,yaml]

  ----

@@ -201,7 +277,7 @@

              platform: [f28]

  ----

  

- Building **for everything else than Fedora 28**:

+ **Building for everything else than Fedora 28**:

  

  [source,yaml]

  ----

@@ -212,7 +288,7 @@

              platform: [-f28]

  ----

  

- Building **only for Fedora 28 and Fedora 29**:

+ **Building only for Fedora 28 and Fedora 29**:

  

  [source,yaml]

  ----

@@ -223,7 +299,7 @@

              platform: [f28, f29]

  ----

  

- ==== Depending on other modules

+ **Building against other modules:**:

  

  Your module can also depend on another modules. Specific streams can be referenced the same way as above in "Building for a specific Fedora release(s) only".

  

@@ -238,7 +314,7 @@

              nodejs: []

  ----

  

- ==== Complex dependencies

+ **A complex example:**

  

  Simple things should simple, complex things should be possible. Let's say my module requires `nodejs` during build and run time. It also requires `build-tools` only during build. To make it even more complex, it also requires a specific stream of a `pizza-module` during build and run time, but only on Fedora 27.

  

@@ -266,7 +342,7 @@

  For even more complex scenarios, please study the https://github.com/fedora-modularity/libmodulemd/blob/master/spec.v2.yaml[modulemd specification].

  

  

- === Binary packages to exclude (optional)

+ === Excluding binary packages (optional)

  

  One source RPM package might produce multiple binary RPM packages. If you don't want to include some binary packages, list them under `filter`.

  

@@ -308,7 +384,7 @@

                  ref: 3.0

              second-package:

                  rationale: Web UI for the first-package.

-                 ref: stable

+                 ref: latest

  ----

  

  === Including profiles and API (recommended)

@@ -357,13 +433,5 @@

                  ref: 3.0

              second-package:

                  rationale: Web UI for the first-package.

-                 ref: stable

- ----

- 

- === Bonus: Converting modulemd v1 to v2

- 

- This video walks through the differences between the legacy modulemd v1 and the current modulemd v2.

- 

- ++++

- <iframe width="560" height="315" src="https://www.youtube.com/embed/kQM_jC8S7bM?rel=0&amp;showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>

- ++++ 

\ No newline at end of file

+                 ref: latest

+ ---- 

\ No newline at end of file

@@ -2,45 +2,39 @@

  

  This page will guide you through the process of updating an existing module.

  

- == Step 1: Update your RPM packages

+ 1. **<<Updating RPM Packages>>** — Pushing new sources.

+ 2. **<<Updaging the Module>>** — Pushing a new version of the modulemd.

+ 3. **<<Updaging the Module>>** — Module is built as a unit. No individual package builds are done.

+ 4. **<<Publishing the Module>>** — Submitting a Bodhi update.

  

- **Goal**: Get updates for your PRM packages pushed into the Fedora Distribution Git (dist-git).

+ == Updating RPM Packages

  

- === Workflow Summary:

- 

- 1. Make changes to your RPM package sources.

- 2. Push your RPM package sources to dist-git.

- 

- === Details:

+ Update your RPM packages the same way you would do traditionally, exept submitting individual package builds.

  

  Useful resources:

  

  * https://fedoraproject.org/wiki/Packaging:Guidelines[Fedora Packaging Guidelines]

  * https://fedoraproject.org/wiki/Package_maintenance_guide[Fedora Package Maintenance Guide]

  

- == Step 2: Bump the module version

- 

- **Goal**: Get your module definition describing the new version pushed into the Fedora Distribution Git (dist-git). This needs to be done even when the modulemd doesn't change.

- 

- === Workflow Summary:

+ == Updaging the Module

  

- 1. Push an empty commit to your module dist-git repository.

- 

- === Details:

- 

- The version of your module is taken from the last commit timestamp. Therefore, in order to submit a new module build, you need to make a new commit. To push an empty commit to your modulemd, run:

+ Even when you don't need to make any changes to the modulemd, you still need to push a new commit to build a new version. 

  

  ----

- $ fedpkg clone modules/nodejs

- $ cd nodejs

+ $ fedpkg clone modules/NAME

+ $ cd NAME

+ $ fedpkg switch-branch BRANCH

  $ git commit --allow-empty -m "update"

- $ git push

+ git push

  ----

  

- == Step 3: Build your module

+ * `NAME` — name of the module

+ * `BRANCH` — name of the stream branch of the module

+ 

+ == Module Build

  

  include::{partialsdir}/submit-module-build.adoc[]

  

- == Step 4: Make your module available to users

+ == Publishing the Module

  

  include::{partialsdir}/submit-module-update.adoc[] 

\ No newline at end of file

no initial comment

rebased onto 9f5287b

11 months ago

1 new commit added

  • one command for pkg + module repo
11 months ago

Can we redirect this to the standard RPM packaging guidelines? I don't really like recommending fedpkg import for anything other than the first creation of the package. Also, we don't have to keep this up to date if we just refer over to the standard RPM guidelines.

This should be updated to note that this is the section we deferred to above for when dealing with packages that don't match their module name. Also note that it can be skipped for dependencies if the module already exists.

Probably useful to note that --exception is passed here because module creation is permitted to skip the BZ step.

We should also open a bug to have it be set implicitly if --namespace == modules

"Note: this was done for you automatically if you did not pass --no-auto-module in the RPM step above"

This is not true currently. That command just returns module-context right now. We need to change this to fedpkg module-build-info BUILD_ID which reports the correct tag.

Better would be to open a bug against fedpkg module-build-info to include the proper format for Bodhi inclusion in the output.

This is still referencing the dead modulemd repository.

We should probably omit this section, since v1 was already obsolete by the time that people started building modules for F28.

1 new commit added

  • fix the fedpkg request-* commands
11 months ago

1 new commit added

  • apply PR feedback
11 months ago

Thanks @sgallagh for the feedback! Again, I agree with everything you said, applied it, and rebuilt the preview.

Pull-Request has been merged by asamalik

11 months ago