The link goes to Debian branded page with little or no useful content at the moment. Filed issue.

My frustration is with packages released with changelog files containing something else than a strict log of release changes. Regardless of tooling!

With "a strict log of release changes" I mean that each section of the logfile summarizes the change between that and the previous section of that file.

Cool stuff, thanks @jonas.smedegaard , @mladen !

Status update:

• squeekboard 1.11.1 in amber is still missing Vcs-* hints
• squeekboard 1.13.0-1pureos1 in byzantium is good

Confirmed, the network-manager-openvpn 1.8.14-1~pureos1 fixes the issue! Thank you @jonas.smedegaard

If you are interested, then I do have suggestions on how to try keep both qualities small - i.e. semi-automated routines - but they evolve around a core principle of treating the parent source (Debian) as the primary and PureOS getting applied on top.

I'd be more than interested ;)

What i'm after is that the changelog content is not related to how the package is prepared. There's tools to aid certain workflows but for d/changelog itself doesn't know anything about that. (what you describe sounds more like frustration about tool failing).

If you are interested, then I do have suggestions on how to try keep both qualities small - i.e. semi-automated routines - but they evolve around a core principle of treating the parent source (Debian) as the primary and PureOS getting applied on top.

To me, best practice of maintaining a fork prioritizes keeping the difference to a minimum over keeping the maintenance work to a minimum.

NB! I certainly welcome reducing the maintanance burden, I am only talking about the priority of those to qualities: Ideally both should be minimal.

Just to make sure we understand each other: What you call "artifacts" are tangible by-products, right? For comparison, what I call "products" are the packages we ship to our users (not throw-away results of test builds).

I have found that doing git merge <debian tag> on top of an already forked and deviated package leads to a package history which interleaves parent and fork-specific changes, which I have not found a way to automatically produce a (to me) comprehensible changelog from.

See also https://source.puri.sm/-/snippets/1165 which contains above script + my notes on surrounding tasks that I have so far been unable to automate, because I have so far found to it too variable across packages.

I am not fluent in Gitlab, but for the local repo part, I use this:

#!/bin/sh

I disagree that we should imply that meshed history is a good practice because I think it is incomprehensible to read a meshed history: It lead to my coming up with the "rebasing" strategy b) referenced in this issue report, and later lead me to file T1048 which triggered the creation of this issue report.

We need to find a balance of being comprehensible for you and workable for developers (most of which just merge in the current Debian *git* packaging into the PureOS packaging. Do you have good suggestion here?

Sorry, I have no suggestions on how to frame preparation routines which involves applying Debian changes on top of PureOS changes as "best practice" for maintaining packages forked from Debian.

Any preparation style regardless of non-metadata contents of the changelog file is acceptable (obeys all "must" in Policy).

Except that this is PureOS and not Debian so while it's certainly a good idea to follow Debian policy we shoudn't simply imply that Debian Policy is the only policy and that we need to adhere to all policy points.

True that it might be bad, but until T1047 is solved Debian Policy is what we got for PureOS!
If you are aware of anything broken or incomplete or overzealous for PureOS then please file a separate report for each issue and link them to T1047.

I disagree that we should imply that meshed history is a good practice because I think it is incomprehensible to read a meshed history: It lead to my coming up with the "rebasing" strategy b) referenced in this issue report, and later lead me to file T1048 which triggered the creation of this issue report.

No, but you are debating whether or not meshing changelogs makes them harder to understand.

There are acceptable (obeys all "must" in Policy) and recommended (obeys all "must" and "should" in Policy) and suggested (follows best practices).

When you do a git merge then changelog files are meshed, and when you follow "strategy b)" you don't. That seems rather consequential to me, not orthogonal.

I'm not debating that debian/changelog could be improved.

No, but you are debating whether or not meshing changelogs makes them harder to understand.

I cannot decipher if release 1.14.12-0.1pureos1~amber1 is just "uploaded" and "backported" compared to release 1.14.12-0.1 - i.e. if the patches mentioned for release 1.14.10-0.1~pureos0~amber1 was applied as well or not.

I don't think [having a rule of "changelog should be a log"] is a good idea though since merging changelogs keeps valuable information around [...] and i don't think this would make it any harder for Debian to look at the diffs.

It would need to *become* a policy rule, it isn't one already.

Thanks for the clarification . sorry that I was unclear.

I am talking about the Debian standard for well-structured patches DEP-3 (not DEP-5)
Debian tracker currently link to a single dumb delta between the forked Ubuntu package and its Debian parent (not DEP-3 patches)
my vision is for PureOS to provide DEP-3 patches to ease reuse outside of PureOS - e.g. linked from same place that now links to dumb Ubuntu patches (not that PureOS provide dumb patches like Ubuntu - which I agree is doable regardless of how packages are prepared but is less helpful than DEP-3 patches).

Evangelos wrote:

this was specifically about updating downstream packages (which was the in the initial title btw ;) ).

@evangelos.tzaras: Is the issue you reported here broadly about any and all best any practice(s) in PureOS missing or undocumented?

I am lost - I don't know what we are discussing here.
Possibly my own fault for a) speaking about things I find relevant before the scope of this issue report was properly established, and b) talking about things I explicitly stated previously that I find out of scope (notably requirements as opposed to best practices).

I would love to have https://tracker.debian.org/ also link to PureOS patches - and I see how that is doable by parsing Debian Policy standards-compliant source packages and look for DEP-5 standards-compliant patches. Which standards should I follow to implement such feature for git branches/commits?

While that sounds like a cool feature, shouldn't the "responsibilities" be reversed? What I mean by that is: If we're carrying PureOS patches shouldn't we (by following the principle of upstream first) be the ones to propose upstreamable patches (to both the parent Debian packaging and/or the relevant upstream projects) instead of making the Debian maintainers having to go hunt for downstream patches?

...or correction: I have seen one tool that lists downstream git branches/commits for cherry-picking - that tool is git itself and is mighty great when you know which packaging style is used. Sure, quite likely the style used by the Debian GNOME team happens to be same (or similar enough) to the one we end up deciding for our git streamlined preparation of Debian packages - but that is missing my kay point:

I would love to have https://tracker.debian.org/ also link to PureOS patches - and I see how that is doable by parsing Debian Policy standards-compliant source packages and look for DEP-5 standards-compliant patches. Which standards should I follow to implement such feature for git branches/commits?

I think most Debian developers use https://tracker.debian.org/

Similary, when we need changes to the packaging of epiphany, we should do that "upstream first" as well: We should have in mind that the epiphany package is maintained as part of Debian and we prefer to not maintain a fork forever, so we should play nice with upstream and try make it easy for them to grab and adopt our changes.

Ok, I will begin drafting a proposed PureOS Policy document, that we can then discuss.

I recommend to treat repo.pureos.net as essential and central for how we work in the PureOS team (i.e. not just an artifact store).

This still leaves the question of best practices with respect to downstream forks of Debian packages (see item a) and item b) in the opening post).

Thanks for expanding @jeremiah.foster you're duplicating partly content from Tracing the package after the upload though. what about dropping that and just referencing the Tracing the package after the upload

@evangelos.tzaras you only have *both* `pueros/latest and pureos/byzantium once byzatium is no longer the current development version. See https://dep-team.pages.debian.net/deps/dep14/ . The upside of pureos/latest is that you'd not be constantly busy with switching the repos default branch and name. It's basically the same as we do within DebianOnMobile with debian/master.

I went ahead and fixed the link.

I could've maybe worded it more clearly in the OP: I was mostly concerned with how to update packages - especially when we're a downstream of Debian.
The question arose because of T1048 and the discussion that ensued around how d/changelog should look like.

I was mostly confused whether this would imply that we would have both pureos/latest and pureos/byzantium.

Yes, let's create a PureOS Policy document. To be clear, we base it on Debian Policy and we add the parts where PureOS deviates. The document is meant to be an authoritative requirements document so ought to use nomenclature to indicate requirement levels either identical to Debian's nomenclature or the IETF nomenclature: https://tools.ietf.org/html/rfc2119

Using pureos/byzantium or pureos/amber with or without -phone is somewhat easier for me since it clarifies which branch is destined for which target suite. In my mind, pureos/latest points to the branch that you work from to create pureos/*.

if this issue report is unrelated to T1048 then I apologize for spreading confusion, and will stand back until perhaps eventually more clear what it is about...

@jeremiah.foster: Among the things you summarize, it seems that only "use appropriate git tag" relates to T1048 and only weakly:
How do those best practices help address T1048?

I reverted to an older document because the NEW Queue is 404'ing at the moment.

Let's keep in mind that we also implement, in the PureOS case, the tools that do package processing. This means we can mandate a set of git tags along with git (obviously) and gbp. I guess the issue with git tags is that some Debian packages do not use git tags, but we can add them for PureOS without much issue no?

For the record, this very issue report was not meant as "this package is totally WRONG" - which is the reason I marked it as severity normal.

This is about what ends up in the *changes* file for the upload, not the changelog entry.

Backports of an updated version of a package that was backported before may have a changelog that merges entries of backports of previous versions, but this is not required.

I propose to reframe this issue to say "best practice(s) is missing/undocumented".

I don't know rules for LTS, but the semi-official (i.e. officially .org hosted but officially unsupported) backports.debian.org seems to a) recomend including all changes compared to newest parent release in topmost changelog section(s):

It is recommended to include all changelog entries since the last version on debian-backports or since stable if it's the first version. You should do this by passing "-v" to dpkg-buildpackage. Eg: "debuild -v0.7.5-2", where "0.7.5-2" is the version in stable.

For Debian packages, there are no forking and resync'ing going on, so the changelog naturally behaves like a "log" - but when "meshing" multiple sources together, the arguably more natural thing to do is to mesh the log as well, which in my opinion is plain wrong and leads to a useless changelog file.

So like

gnome-calls (0.3.2-1pureos1) byzantium; urgency=medium
gnome-calls (0.3.0-2pureos2) byzantium; urgency=medium
gnome-calls (0.3.0-2pureos1) byzantium; urgency=medium
gnome-calls (0.3.0-1pureos1) byzantium; urgency=medium
gnome-calls (0.3.2-1) experimental; urgency=medium
gnome-calls (0.3.0-2) experimental; urgency=medium
gnome-calls (0.3.0-1) experimental; urgency=medium

?

Imagine we reach a conclusion to "find a criteria in the absence of any other authoritative source and to find consensus how to handle that" - does that mean we can close this issue report? No. That is my point.

It's not meta.

This issue says "let's discuss the seemingly 2 existing practices", and T1011 and T1012 says "we need the best practice automated".

My point is that we cannot mandate "merging Debian tags", because that implies a parent Debian package prepared and tagged in a way compatible with gbp which is not always the case.

@jonas.smedegaard point taken. I read that in relation to T1011 and T1012 above which kind of would codify what's asked here.

I agree that (if we want to) we can mandate that package preparation must be done with git and must use gbp.
My point is that we cannot mandate "merging Debian tags", because that implies a parent Debian package prepared and tagged in a way compatible with gbp which is not always the case.

sorry, didn't mean to discredit you, @guido - just appears to me that this issue was filed by @evangelos.tzaras.

(notice how each of the suggestions have some sort of bias...)

While git, git-buildpackage, and tagging releases in git are all popular, they are not required in Debian and therefore cannot be required in PureOS either.

Please do not expand this issue to become a meta discussion about what is common and what is uncommon: That is quite important to figure out but as separate issues.