Haikuports: [META] Documentation for various variables and new HaikuPorts practices

[alaviss]

As the GCI ended, I realize there were many undocumented practices at HaikuPorts, namely:

• [x] libVersion, libVersionCompat for library version tracking
• [x] commandBinDir and friends to strip secondaryArchSuffix from binaries for secondary architectures
• [ ] Versioning convention for ports that use development sources
• [ ] Whether to ship debuginfo with binaries
• [ ] Styling for HOMEPAGE variable
• [x] GLOBAL_WRITABLE_FILES and USER_SETTINGS_FILES position within the recipe

There were undocumented input variables:

• [ ] cmakeDirArgs, a convinience variable for cmake ports that uses GNUInstallDirs or simillar modules (#2074)
• [ ] Various variables that relates to SECONDARY_ARCHITECTURES, namely: secondaryArchSuffix, effectiveTargetArchitecture (#1854)
• [ ] [sysconfDir][1], the variable containing path to the relocatable settingsDir on the file system

Also, there's a lack of guidelines for packages of various languages:

• [ ] python setuptools-based packages, currently for packaging we use constructs like this
• [ ] go-based packages, currently we've one pending (#2079)

This issue would serve as a tracker for the documentation status of the items listed above.

[pulkomandy]

On Thu, Jan 18, 2018 at 01:56:30AM +0000, alaviss wrote:

As the GCI ended, I realize there were many undocumented practices at HaikuPorts, namely:

We have documented only things related to the "core" of haikuporter.
Some of the things you list should be added there:

• [ ] Add ~<vcs> to ports that doesn't use an official release but instead uses a newer version (but not tagged) from \

I think this is already somewhat documented in the version comparison
spec (but not in the haikuporter wiki, you have to dig into the HPKG
file format spec to see how version compare works). Basically, if you
add a .something to a recipe, it is considered a newer version
(so 1.4.2 > 1.4). But if you add a ~something, it is considered a
pre-release (so 1.4~beta < 1.4)

Using ~git is actually not a very good idea, because then you can't
change the version if you point to a different git commit. We should do
it like debian, that is 1.4~20180118 or similar, to be completely safe.

• [ ] libVersion, libVersionCompat for library version tracking
• [ ] commandBinDir and friends to strip secondaryArchSuffix from binaries for secondary architectures
• [ ] Styling for HOMEPAGE variable
• [ ] python setuptools-based packages, currently for packaging we use constructs like [this][0]

These are local to a recipe, so they should not be documented in the
existing wiki page which documents things used by haikuporter itself.
However, we can make a new wiki page with these patterns (and links to
sample recipes for each).

• [ ] go-based packages, currently we've one pending (#2079)

I'm surprised, because it is currently not possible to build Go for
Haiku. We had an old Go port but it is not possible to build it since
code.google.com was archived.

• [ ] Whether to ship debuginfo with binaries

We should define a policy for this, then document it.

There were undocumented input variables:

• [ ] cmakeDirArgs, a convinience variable for cmake ports that uses GNUInstallDirs or simillar modules (#2074)
• [ ] Various variables that relates to SECONDARY_ARCHITECTURES, namely: secondaryArchSuffix, effectiveTargetArchitecture (#1854)

These should be added to the existing page documenting input and output
variables.

[KapiX]

2018-01-18 7:39 GMT+01:00 Adrien Destugues [e-mail]:

These are local to a recipe, so they should not be documented in the
existing wiki page which documents things used by haikuporter itself.
However, we can make a new wiki page with these patterns (and links to
sample recipes for each).

I'd say they belong here:
https://github.com/haikuports/haikuports/wiki/HaikuPorter-Guidelines

[fbrosson]

I've just improved the wiki a little with these two changes:

• Recommend GLOBAL_WRITABLE_FILES & USER_SETTINGS_FILES before PROVIDES
• Mention CONFLICTS, REPLACES, SUPPLEMENTS, FRESHENS, srcGitRev, libVersion and libVersionCompat.

(That's a tiny step forward, compared to what still needs to be done...)

[fbrosson]

More improvements done in the wiki:
Suggest a definition for libVersionCompat and the recommended place for commandSuffix and commandBinDir. Improve the paragraph about the Source URI.

[alaviss]

@fbrosson What is the current versioning convention for ports that use development sources? This should be discussed so that future ports could be aligned to a single convention.

IIRC we have agreed to <release>.<date><vcs> scheme, but it appears not the case anymore.

[fbrosson]

You are right. There seems to be a <release>.<date><vcs> scheme, but I think it's not official.
The reason we switched to a <release>_<date> scheme for all the *_libretro recipes (for the libretro cores) was that we were looking for an alternate convention to:

• workaround the upgrade issue we bumped into, when we used the <release>.git<date> scheme for bsnes_libretro and fbalpha_libretro, iirc, because that was not a good scheme and we only noticed it after the merge.
• make it clear that the <date> was not part of the upstream versioning scheme.

IMHO the use of the underscore has two advantages:

• It makes it clear that the <date> is part of our internal versioning.
• it drops the <vcs> part which is also not really needed since it is obvious that all these recipes are using a git snapshot.

I'm sorry if I started a new scheme. It was not my intention. I just wanted to workaround an issue.
That said, we can escape that scheme and switch back any other scheme at the next release of each core. But it seems some ports won't ever see their version bumped :(

To summarize: I'm not against switching the scheme, although I think it is not necessary.

[alaviss]

Your scheme looks fine to me. But IMHO, we should start a vote on whether this scheme should be promoted to be the preferred scheme for use in HaikuPorts, then documents it in the Guidelines.

[fbrosson]

Thanks!
For the vote, I don't know if this is really necessary.
Maybe we can just mention (in the wiki) the two versioning schemes and let each contributor choose what seems most appropriate.

That said, I'm not against a vote. I just fear that the outcome might not satisfy everyone. Hence the suggestion to allow each contributor to stick to his prefered scheme.

I think what the general rule is that whenever a recipe needs to be switched to a snapshot a discussion occurs in the PR. This seems to be OK for now and has the advantage of giving more freedom :)

[fbrosson]

Oops, I read _"a vote on whether this scheme should be promoted to be the preferred scheme"_ but understood _"a vote on whether this scheme should be promoted to be the highly recommended scheme"_.

I'd say that we don't really need to vote. A natural trend will probably appear, with time, if one scheme is prefered over the others. But I'm very honored by your proposal for a vote ;)

[pulkomandy]

On Sun, Mar 11, 2018 at 03:18:43AM -0700, alaviss wrote:

Your scheme looks fine to me. But IMHO, we should start a vote on whether this scheme should be promoted to be the preferred scheme for use in HaikuPorts, then documents it in the Guidelines.

I won't vote on anything unless someone has a summary of how each of
them compares (in terms of newer/older) with the official releases.

This is the important thing here, we want the pre-releases to be before
the matching official releases, and we want the "patches" to be after
it.

So we should carefully check what happens with each scheme in that
regard.

Then, I don't really care which one is used, as long as the comparisons
work as expected.

[fbrosson]

Both schemes work correctly wrt the official releases vs snapshots chronology.

BTW the motivation for the switch from x.y.z.git<date> to x.y.z_<date> was that it allowed to get rid of the "git" that we had incorrectly put before the date, instead of after it.)
(Of course, I checked that _ > . before switching to the alternate scheme.)