#835 Fix conversion issues.
Merged 5 months ago by ignatenkobrain. Opened 5 months ago by vondruch.
vondruch/packaging-committee fix-versioning  into  master

@@ -61,18 +61,18 @@ 

  

  The methods for dealing with most of these issues involves potentially removing some information from the `+Version:+` tag while imposing additional structure onto the `+Release:+` tag. There are potentially three fields which comprise the structured `+Release:+` tag:

  

- * package release number ()

- * extra version information ()

- * snapshot information ()

- * minor release bump ()

+ * package release number (`<pkgrel>`)

+ * extra version information (`<extraver>`)

+ * snapshot information (`<snapinfo>`)

+ * minor release bump (`<minorbump>`)

  

  The package release number MUST always be present while the others may or may not be depending on the situation.

  

  Those items which are present are combined (with periods to separate them) to construct the final `+Release:+` tag. In the usual notation where square brackets indicate that an item is optional:

  

- * `+[.+``+][.+``+]%{?dist}[.+``+]+`

+ * `+<pkgrel>[.<extraver>][.<snapinfo>]%{?dist}[.<minorbump>]+`

  

- The actual values to be used for those three fields are situational and are referenced in the sections below. Note that your particular situation might not result in the use of or , and in most situations won't be used at all. Simply do not include those which you don't have.

+ The actual values to be used for those three fields are situational and are referenced in the sections below. Note that your particular situation might not result in the use of `+<extraver>+` or `+<snapinfo>+`, and in most situations `+<minorbump>+` won't be used at all. Simply do not include those which you don't have.

  

  === Upstream has never chosen a version

  

@@ -82,22 +82,22 @@ 

  

  It's possible that upstream uses characters besides ASCII letters (upper and lower case), digits and periods in its version. They must be removed and potentially replaced with valid characters. Any such alterations MUST be documented in the specfile. It is not possible to cover all potential situations here, so it is left to the packager to alter the upstream versioning scheme consistently.

  

- After altering the version to be free of invalid characters, see link:#Unsortable_versions[#Unsortable versions] below if the modifications, when applied to successive releases from upstream, will not order properly.

+ After altering the version to be free of invalid characters, see <<Unsortable versions>> below if the modifications, when applied to successive releases from upstream, will not order properly.

  

  === Unsortable versions

  

- When upstream uses a versioning scheme that does not sort properly, first see if there is any portion which can be removed from the right side of the version string such that the remainder is sortable. This is often possible if upstream uses a sequence like ("1.2pre1", "1.2pre1", "1.2final"). If so, use the removed portion as above, and the remainder as the package version. If this splitting leaves a leading or trailing period in either value, remove it.

+ When upstream uses a versioning scheme that does not sort properly, first see if there is any portion which can be removed from the right side of the version string such that the remainder is sortable. This is often possible if upstream uses a sequence like ("1.2pre1", "1.2pre1", "1.2final"). If so, use the removed portion as `+<extraver>+` above, and the remainder as the package version. If this splitting leaves a leading or trailing period in either value, remove it.

  

- If this is not possible, use Version: 0 and move the _entire_ version string into .

+ If this is not possible, use Version: 0 and move the _entire_ version string into `+<extraver>+`.

  

  === Snapshots

  

- All snapshots MUST contain a snapshot information field () in the `+Release:+` tag. That field must at minimum consist of the date in eight-digit "YYYYMMDD" format. The packager MAY include up to 17 characters of additional information after the date. The following formats are suggested:

+ All snapshots MUST contain a snapshot information field (`+<snapinfo>:+`) in the `+Release:+` tag. That field must at minimum consist of the date in eight-digit "YYYYMMDD" format. The packager MAY include up to 17 characters of additional information after the date. The following formats are suggested:

  

- * `+YYYYMMDD.+`

- * `+YYYYMMDD+`

+ * `+YYYYMMDD.<revision>+`

+ * `+YYYYMMDD<scm><revision>+`

  

- Where is a short string identifying the source code control system upstream uses (e.g. "git", "svn", "hg") or the string "snap". is either a short git commit hash, a subversion revision number, or something else useful in identifying the precise revision in upstream's source code control system. Obviously if CVS is used, no such revision information exists, so it would be omitted, but otherwise it SHOULD be included.

+ Where `+<scm>+` is a short string identifying the source code control system upstream uses (e.g. "git", "svn", "hg") or the string "snap". `+<revision>+` is either a short git commit hash, a subversion revision number, or something else useful in identifying the precise revision in upstream's source code control system. Obviously if CVS is used, no such revision information exists, so it would be omitted, but otherwise it SHOULD be included.

  

  === Prerelease versions

  

@@ -105,7 +105,7 @@ 

  

  === Release and post-release versions

  

- For the field of the `+Release:+` tag, use an integer beginning with 1 and increasing for each revision of the package. Release and post-release versions MUST use a `+Release:+` tag greater than or equal to 1.

+ For the `+<pkgrel>+` field of the `+Release:+` tag, use an integer beginning with 1 and increasing for each revision of the package. Release and post-release versions MUST use a `+Release:+` tag greater than or equal to 1.

  

  === Upstream makes unsortable changes

  

@@ -115,7 +115,7 @@ 

  

  Sometimes, you may find yourself in a situation where an older branch needs a fix, but the newer branches are fine. For example, if pkg = 1.0-1%\{?dist} in F and F, and only F needs a fix. Normally, you would need to bump the release in each of the branches to ensure that F < F, but that is a waste of time and energy for the newer branches which do not need to be touched.

  

- In this case, you MAY set to an in integer beginning with '1' and increasing by one for each minor bump you need to do. Remove once you are able to increase the package release normally without introducing ordering issues.

+ In this case, you MAY set `+minorbump+` to an in integer beginning with '1' and increasing by one for each minor bump you need to do. Remove `+minorbump+` once you are able to increase the package release normally without introducing ordering issues.

  

  == Rawhide is allowed to lag temporarily

  

Probably all the preformatted text enclosed in <> was missing and a link was broken.

I have not tested this by any means, so the output might not be much better ....

Pull-Request has been merged by ignatenkobrain

5 months ago

I've been so buried in my own drafts I didn't realize how bad the actual guideline page was.

It's not hard to preview things directly in the browser from the PR; I did that and it certainly looks better.

@tibbs similarly to you, fixing this was an (undesired) side-effect of doing something else, so I did not really bother with previews ;)

@ignatenkobrain I see the updated version is already on docs. Is there a chance to add some reference from which commit it was actually generated, so I could be able to see what is the actual version comparing to the sources? Or is it somehow automatically published after commit/merge?

@ignatenkobrain there is still broken "Package Versioning Examples" link. It does not look we have that page in new documentation ....

That page was never really completed. My original intent was that the examples page would stay in the wiki and not be under Packaging at all, so that the community could provide examples. But given how easy it is for someone to send a PR now, I guess it's not really a problem to have it under the examples section in these new guidelines pages.

Still, it would need to actually be written. I have done some private work on that in concert with the other work I've been doing for the versioning overhaul, and will provide some content for that page once we actually decide what we're going to do.

As for indicating the docs pages, that is all still under development. I think the rebuilds still happen manually though I believe the plan is to have them driven by commits. (I can't comprehend why they aren't at least done by a cron job that runs a few times an hour, but it's not my system.) I would assume there must be some way to indicate the point HEAD was at when they were generated, but I have no idea how to do it.

Metadata