#25 fix typos
Merged 8 months ago by asamalik. Opened 8 months ago by nphilipp.
fedora-docs/ nphilipp/modularity master--typos  into  master

@@ -1,6 +1,6 @@ 

  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.

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

  

  ----

  $ fedpkg clone modules/NAME

@@ -4,7 +4,7 @@ 

  * 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 getting the `MODULE_BUILD_ID` is running the same command as in the previous step:

  

  ----

  $ fedpkg module-build-info BUILD_ID

@@ -30,11 +30,11 @@ 

  

  image::mod-doc-release.png[,80%,]

  

- Releases are the generations of Fedora e.g. “Fedora 28”, “Fedora 29”, or “epel 7”.

+ Releases are the generations of Fedora e.g. “Fedora 28”, “Fedora 29”, or “EPEL 7”.

  

  Each release can only contain one major version of every package (by policy).

  In general, Fedora tends to ship the latest stable versions of software available.

- At the same time, packages need to maintain a certain API/ABI stability throughout the lifecycle of the release they are part of.

+ At the same time, packages need to maintain a certain API/ABI stability throughout the life cycle of the release they are part of.

lifecycle in this context is a single word: https://en.wikipedia.org/wiki/Product_lifecycle

Heh, the WP page you linked isn't all to sure about it either, just grep for life cycle (two words) on it. ;)

I've looked into this a little further and apparently terms like this on their own should be written as two separate words—life cycle—but the two words are put together when used as a modifier for yet another word—lifecycle management.

What do you think?

  

  The problem with this approach is finding the right balance of being too fast vs. too slow.

  For example, developers in general tend to prefer the newest versions of software, while server administrators want API/ABI stability for a longer period of time.

@@ -47,7 +47,7 @@ 

  *Modules* are collections of packages representing a logical unit e.g. an application, a language stack, a set of tools.

  These packages are built, tested, and released together.

  

- Each module defines its own lifecycle which is closer to the upstream rather than the Fedora release.

+ Each module defines its own life cycle which is closer to the upstream rather than the Fedora release.

  

  Modules are the mechanism of delivering multiple streams (versions) of software for the same release.

  This also works the other way round, the same stream for multiple releases.

@@ -65,7 +65,7 @@ 

  

  image::mod-doc-repositories.png[,80%,]

  

- Artifacts are consumable outputs of the build and release processes e.g. an iso image, an RPM repository, a container base image, or an ostree tree.

+ Artifacts are consumable outputs of the build and release processes e.g. an ISO image, an RPM repository, a container base image, or an OSTree tree.

  

  Modules will be delivered as an RPM repository that will work on top of existing releases.

  This repository will also be available in the Fedora container base image, enabling users to build containers with multiple versions of software.

@@ -20,7 +20,7 @@ 

  

  However, streams can also promise different things such as *stability*. A good example of this is the _calc_ package in Fedora which is maintained in two upstream branches: _stable_ for the latest stable release and _unstable_ for the latest development version. Using modularity, this package could be built as a _calc_ module in two different streams: _stable_ and _unstable_.

  

- In addition to the version promise, streams are also a way for packagers to communicate the *level of maintennance*. Does the maintainer plan to apply every minor patch? Will they apply security fixes quickly? Or is the module updated only twice a year? This can also be part of the promise.

+ In addition to the version promise, streams are also a way for packagers to communicate the *level of maintenance*. Does the maintainer plan to apply every minor patch? Will they apply security fixes quickly? Or is the module updated only twice a year? This can also be part of the promise.

  

  Other different example could be a stream that provides the software compiled using some experimental flags increasing the performance.

  

@@ -46,7 +46,7 @@ 

  

  Context is used to distinguish binaries built for different Fedora releases. Thanks to https://fedoraproject.org/wiki/Infrastructure/Factory2/Focus/StreamExpansion[stream expansion], modules can also be built against multiple streams of other modules, i.e. different versions of a language runtime etc.

  

- The value is generated by the build system and is usually hidden from the user as it doesn't have any informational value by itself — it is a hash. However, the client tooling consuming this valie can present it in a useful way.

+ The value is generated by the build system and is usually hidden from the user as it doesn't have any informational value by itself — it is a hash. However, the client tooling consuming this value can present it in a useful way.

  

  One way of representing the context could be listing the Fedora releases for which a certain module has been built.

  

@@ -22,7 +22,7 @@ 

  

  == Consuming the modular packages

  

- If a user desires to use the optioanl Modular repositories in order to consume non-default versions of software, there will be some new concepts introduced in the client tooling to manage them.

+ If a user desires to use the optional Modular repositories in order to consume non-default versions of software, there will be some new concepts introduced in the client tooling to manage them.

  We outline these below.

  

  === Enabling a module

@@ -56,6 +56,6 @@ 

  

  ==== Running multiple versions using containers

  

- Modularity brings parallel availability, not parallel installability. There are other technologies i.e. linux containers or software collections that deal with this.

+ Modularity brings parallel availability, not parallel installability. There are other technologies e.g. Linux containers or software collections that deal with this.

  

  All the steps described above can be used in a container the same way as on a traditional system. Producing up-to-date containers with multiple versions of software in an automated way is also one of the goals.

@@ -19,7 +19,7 @@ 

  * The "platform" pseudo-module cannot be explicitly enabled, installed,

    deleted, or have its stream changed.

  * A module is specified by its name, stream, version, context, and

-   architecture (eg., "module:stream:version:context:arch").

+   architecture (e.g., "module:stream:version:context:arch").

  ** If a module has a default stream defined on a system, "stream" may be

     omitted. Otherwise, "stream" must be explicitly provided.

  ** For a given "module:stream", "version" can always be omitted. If

@@ -98,7 +98,7 @@ 

  

  * Updating a module will update all installed packages that belong to

    the enabled module stream--regardless if the packages were installed

-   by an install profile or ad-hoc.

+   by an install profile or ad hoc.

  

  == Module disablement

  

@@ -111,7 +111,7 @@ 

  

  * Uninstalling a module removes all the packages that belong to the

    module and disables it.

- * Ad-hoc removal of all packages from an installed module does not

+ * Ad hoc removal of all packages from an installed module does not

    disable the module.

  

  == Module locking

@@ -13,7 +13,7 @@ 

  Most of the discussions happen on this IRC channel.

  

  https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/[devel@lists.fedoraproject.org]::

- The Modularity WG doesn't have a dedicated mailng list.

+ The Modularity WG doesn't have a dedicated mailing list.

  Instead, the Fedora Devel mailing list is used time to time for more complex decisions or announcements.

  

  https://lists.fedoraproject.org/archives/list/server@lists.fedoraproject.org/[server@lists.fedoraproject.org]::

@@ -25,7 +25,7 @@ 

  Currently, there are two alternating meetings on Tuesday:

  

  Modularity WG::

- A formal meeting of the Modularity WG to discuss, post updates, and make dedisions.

+ A formal meeting of the Modularity WG to discuss, post updates, and make decisions.

  

  Office Hours::

  No formal agenda, members of the Modularity WG promise to be present at this time for questions or discussion.

file modified
+4 -4

@@ -10,8 +10,8 @@ 

  How does this differ from Software Collections (SCLs)?::

      Modularity is about building multiple versions of packages, and making them all available to users.

      SCLs are about installing software in parallel using RPM.

-     These two don’t overlap, they complement each other. You can build a Modular SCL.

- Couldn’t we solve this with having compat- packages, or putting versions into package names for different version streams?::

+     These two don’t overlap, they complement each other. You can build a modular SCL.

+ Couldn’t we solve this with having compat packages, or putting versions into package names for different version streams?::

      That works technically, but the packaging workload doesn’t scale, and dependency interactions become complex. This will let packagers make more content available to users without an explosion of effort.

      Modules also help to solve the discoverability problem.

      For example, is httpd v2.4 in a package called httpd-2-4 or http-2?

@@ -23,9 +23,9 @@ 

      User experience: A repository is a source of software provided by a vendor, not necessarily representing a single application, language stack, or any other logical unit of software.

      A repository typically contains multiple applications, stacks, etc.

      We do not want to change this concept.

- Are you going to produce all versions? What lifecycles and versions are envisioned?::

+ Are you going to produce all versions? What life cycles and versions are envisioned?::

      We are developing the technology such as the build pipeline and client tooling to enable contributors to build multiple versions.

-     We envision longer lifecycles of stacks mainly for server, and devel/rolling releases of some stacks for developers.

+     We envision longer life cycles of stacks mainly for server, and devel/rolling releases of some stacks for developers.

      However, contributors to the Fedora project will be the deciders and maintainers of any versions that are available.

  I can just ‘dnf downgrade’ to get an older version.. Why do we need modularity?::

      Using an older version that is no longer maintained can be dangerous, mostly because of the lack of security updates.

@@ -1,6 +1,6 @@ 

  = What is Modularity

  

- Modularity introduces a new optional repository to Fedora called Modular (often referred to as the "Application Stream" or AppStream for short) that ships additional versions of software on independent lifecycles.

+ Modularity introduces a new optional repository to Fedora called Modular (often referred to as the "Application Stream" or AppStream for short) that ships additional versions of software on independent life cycles.

  This way users can keep their operating system up-to-date while having the right version of an application for their use case, even when the default version in the distribution changes.

  

  image::modularity-appstream-overview.png[,100%,]

@@ -12,7 +12,7 @@ 

  

  Different users have different needs.

  Developers want the latest versions possible, system administrators want stability for longer period of time.

- There are many Linux distributions out there, each targetting a different audience, for example Fedora vs CentOS.

+ There are many Linux distributions out there, each targeting a different audience, for example Fedora vs. CentOS.

  

  Fedora generally ships the latest stable versions of its component packages when it is released twice per year.

  That is convenient for desktop users and developers.

@@ -9,7 +9,7 @@ 

  

  == RPM Sources

  

- 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**.

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

  

  === Repositories and Stream Branches — New packages

  

@@ -43,7 +43,7 @@ 

  

  == Module Definition

  

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

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

  

  === Repositories and Stream Branches — New modules

  

@@ -2,7 +2,7 @@ 

  

  This page walks you through building modules locally on your machine.

  

- == Prerequisities

+ == Prerequisites

  

  You need to install the `module-build-service` as well as `fedpkg`:

  

@@ -19,7 +19,7 @@ 

  

  == Step 1: Build your module

  

- Local builds are started using `fedpkg` from whithin your dist-git repository.

+ Local builds are started using `fedpkg` from within your dist-git repository.

  

  For example, to submit a build of the `testmodule:master` module, run:

  

@@ -45,7 +45,7 @@ 

              - package-two        # <- Binary RPM package name

      

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

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

+     # (Helping users with installation by providing predefined groups)

      profiles:

          default:  # <- Name of the profile

              description: A standard installation.

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

  === License of this modulemd file

  

  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.

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

  

  [source,yaml]

  ----

@@ -121,7 +121,7 @@ 

  

  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.

+ 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 run time, please see the Advanced section below.

  

  [source,yaml]

  ----

@@ -222,7 +222,7 @@ 

  

  === Building in a specific order (optional)

  

- Packages are built in batches. By default, all packages are part of a single group, and therefore built concurently.

+ Packages are built in batches. By default, all packages are part of a single group, and therefore built concurrently.

  

  To build packages in a specific order, assign them to multiple build groups. Build groups are identified by an integer. Groups with lower number are built first. Negative values are allowed, `0` is the implicit default value.

  

@@ -262,8 +262,8 @@ 

  modules can be

  

  * built against other modules

- * require other modules during runtime

- * built agains one or more streams of the same module

+ * require other modules during run time

+ * built against one or more streams of the same module

  * work with one or more streams of another module

  

  **Building only for Fedora 28**:

@@ -434,4 +434,4 @@ 

              second-package:

                  rationale: Web UI for the first-package.

                  ref: latest

- ---- 

\ No newline at end of file

+ ----

@@ -4,11 +4,11 @@ 

  

  == Setting or changing a default

  

- Submit an issue to Fedora Releng in https://pagure.io/releng/issues[pagure.io/releng]. You also need to https://fedoraproject.org/wiki/Changes/Policy#For_developers[submit a Fedora Change].

+ Submit an issue to Fedora Release Engineering in https://pagure.io/releng/issues[pagure.io/releng]. You also need to https://fedoraproject.org/wiki/Changes/Policy#For_developers[submit a Fedora Change].

  

  To check the current defaults, have a look at the https://pagure.io/releng/fedora-module-defaults[fedora module defaults repository].

  

  Setting or changing default stream of a module will be considered based on the following rules:

  

  * If the module stream does not mask any part of the Traditional RPM repos, it may be set as a default stream. For example, any module that is entirely a leaf or one that fulfills the function of a package moved from the traditional repos into the modular repos (e.g. `nodejs:8` might replace the `nodejs` traditional package)

- * If the module stream masks part of the Traditional RPM repos (e.g it replaces an existing RPM or it introduces a non-trivial set of conflicts) it may not be made a default stream without the express permission of FESCo. Release engineering will be responsible for escalating any PR that is questionable on this point to FESCo for a final decision. 

\ No newline at end of file

+ * If the module stream masks part of the Traditional RPM repos (e.g it replaces an existing RPM or it introduces a non-trivial set of conflicts) it may not be made a default stream without the express permission of FESCo. Release Engineering will be responsible for escalating any PR that is questionable on this point to FESCo for a final decision.

@@ -42,7 +42,7 @@ 

  

  In some cases, there are many suitable alternatives for for one meaning i.e. "dev", "devel", and "development". We believe that choosing one that would be consistently used across all modules that need such profile would lead to a better user experience. The ones identified are listed below:

  

- * "default" a default profile for a "standard" instalation, should the module have something like this

+ * "default" a default profile for a "standard" installation, should the module have something like this

  * "devel" for development-related profiles

  * "client" only the client component of a piece of software (e.g. database client)

  * "server" only the server component of a piece of software (e.g. database server)

@@ -3,20 +3,20 @@ 

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

  

  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.

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

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

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

  

  == Updating RPM Packages

  

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

+ Update your RPM packages the same way you would do traditionally, except 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]

  

- == Updaging the Module

+ == Updating the Module

  

  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. 

  

@@ -4,7 +4,7 @@ 

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

  ++++

  

- From the user perspective, modules are like release-independent package groups on independent lifecycles, providing alternative streams of content to Fedora.

+ From the user perspective, modules are like release-independent package groups on independent life cycles, providing alternative streams of content to Fedora.

  

  == Enable modular repositories

  

This should fix all typos I found with aspell. I'm a bit unsure about run-together words, i.e.:

  • runtime vs. run time, here I used one word for e.g. language runtimes and two words for "the time when the program is run".
  • hotfix, while dictionaries don't know it I left it as is because it's a household name in IT.
  • lifecycle vs. life cycle, here I used two words as that's what dictionaries do.

@nphilipp as always, thanks for the fixes!

I've put a comment inline about "lifecycle" vs. "life cycle". I believe that in this context it's a single word: https://en.wikipedia.org/wiki/Product_lifecycle

Otherwise looks good to me.

Heh, the WP page you linked isn't all to sure about it either, just grep for life cycle (two words) on it. ;)

I've looked into this a little further and apparently terms like this on their own should be written as two separate words—life cycle—but the two words are put together when used as a modifier for yet another word—lifecycle management.

What do you think?

OK, I think we should do it your way! :-)

After a very quick couple of searches, it looks like the world is not sure what to do in this case. It looks like both are correct. But all the dictionaries I've tried are much more happy with having it as two words. So, yeah, interesting, learning every day. Merging.

Pull-Request has been merged by asamalik

8 months ago