I think it makes sense to distinguish between a) package style (i.e. how we want to compose our final .deb packages released into PureOS) and b) package preparation style (i.e. how we want to keep track of the source components used for our package releases).

This issue seems to be about package preparation style - listing two styles both involving git-tracking sources sync'ed with similar-style preparation in Debian.

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.
So this can only possibly be a discussion on best practices - not policy.
(possibly that was implied in the issue description but I think it helps to state it explicitly).

I find that issues work best when framed as something wrong - which can then be resolved either by disputing that the problem is real or by fixing it or by deciding that it exists but should not be fixed.

@evangelos.tzaras: Would you agree with reframing this "discussion issue" by changing the title e.g. to one of these?:

pureos: unclear how to update downstream forks

pureos: unclear how to best update downstream forks

pureos: unclear which is the correct way to update downstream forks

pureos: undocumented how to best update downstream forks

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

While i'm not suggesting we enforce anything like gbp atm i don't think there's any argument why we can't enforce things in PureOS for *forked* packages that aren't enforced in Debian.

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

There *certainly* is bias since I wrote this bug after updating several packages in https://source.puri.sm/pureos/packages that lead me to the above questions. So this came abouts because i tried to understand how the PureOS team does it's work *there*.

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

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.

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

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.

…not without explaining what 'debian tags' means (we can always come up with a mergable tag even if there's no git upfront and we have to even create that or if the tag is missing, has odd format, ...).

So to make this into a general rule it needs to consider some corner cases (or initially just single those out and handle the (nowadays) common case of a mergable git from salsa that has DEP-14 compatible tagging)

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

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

Yes, as currently framed this issue can be seen as being solved by T1011 and T1012, but that is arguably because a) this issue is overly broadly scoped and b) T1011 and T1012 assumes that one best practice already exist and only need to be codified.

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

sounds good to me!

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?

Therefor, I'd sketch out the best practice as; use git as the DVCS, use gbp as the DVCS to control package meta-data, name the relevant branches "pristine-tar, upstream, pureos/latest or pureos/byzantium", use appropriate git tag, use debspawn to build package in isolation, upload with dput-ng.

What's the view on this practice that I've outlined above?

@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?

Do you perhaps mean to imply that whatever gbp dch generates should be used as-us - not edited and extended to make more sense?

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

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.

So while I was primarily interested in what the recommended practice is on updating downstream packages (because these were the kinds of packages I've been working on in PureOS) I definitely don't mind if the broader issue of how any package should be updated is discussed and subsequently documented :)

So having all that said: I'm already following those best practices (except for uploading with dput - because the packages that I've worked on are handled through the magic of https://source.puri.sm/Librem5/deb-build-jobs), so consider this a +1 from me (for the general approach).

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

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

The whole exercise of pkg-phosh, pkg-calls repos is basically that we can treat phosh, calls etc as downsteam forks from Debian, so it would just be the same.

Therefor, I'd sketch out the best practice as; use git as the DVCS, use gbp as the DVCS to control package meta-data, name the relevant branches "pristine-tar, upstream, pureos/latest or pureos/byzantium", use appropriate git tag, use debspawn to build package in isolation, upload with dput-ng.

@jeremiah.foster thanks for the proposal. I can certainly subscribe to this since that's the tooling we're using on the phone side in (afaik) all places (except for dput-ng as @evangelos.tzaras noted above). Here's several more suggestions:

• clearly label as 'best practice'. this is not meant as a rule that makes peoples brain explode if package doesn't fit for any reasons.
• consider the archive (repo.pureos.net) mostly as an artifact store. The source for investigations, bug fixing, etc should be the git repository. This would help T1048 etc. since i think assumptions about the role of the archive are part of the discussion in that bug.
• if we settle on a recommended tooling we want to have a good reference repo with e.g. a suitable d/gbp.conf, dput-ng config, d/pureos-ci.yml, ...

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

To me, this is strongly tied to the Purism spirit of "upstream first":

"Upstream first" does not mean we should only develop upstream, nor that we should wait for upstream integration before integrating locally.
Instead, "upstream first" means that we should encourage upstream adoption of our work.

"Upstream first" applies not only to upstreams of packages but also to upstreams of packaging.

Concrete example: When we need changes to epiphany, we should do it "upstream first" which means that we whould have in mind that epiphany is maintained as part of GNOME 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.

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.

If we look at packages as merely an artifact of our packaging process, then we cannot apply the "upstream first" approach for packaging, because our packaging upstream consider their packages not merely artifacts but the official truth of what constitutes "The Source" of the package.
Debian has no formal standardized process-to-generate-a-source-package - the source package is officially the starting point, everything happening in git is in Debian unofficial.

Yes, we can do better and more efficient for our own process to generating source packages. Wwe cannot make Debian fit into that better streamlined scheme of things, however. We can try reshape Debian e.g. by adding tags to match our streamlined scheme (as @jeremiah.foster tsuggests), but would not aid in "upstream first" - it would only help ourselves in our (then likely prolonged!) fork maintenance.

Packages produced "upstream first" invites our parent distribution - Debian - to adopt parts relevant for them, by making it easy to recognize what we forked from them and what we changed.

Packages might also be maintained "upstream first", by using same scheme as the upstream package (i.e. not streamlining our maintenance but instead zig-zagging between the numerous varying schemes used for each package in Debian).
I agree that it makes sense that we streamline our package maintenance - as a general guideline (and then exceptionally use a different style as was shown to make sense e.g. for firefox-esr which does not use gbp import in Debian and therefore became quite complicated if used for PureOS).
I disagree, however, that we should treat generated packages as merely "artifacts" because those are the very thing that ties us back to Debian.

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.

yes, and Debian's GNOME team uses git on salsa and prefer MRs there (at least that form of interaction works very well with them). So i'd say basing things on salsa's git (which would be another best practice and something lots of packages in /pureos/packaging already do) would be upstream first. The fact that Debian treats the archive as 'the truth' (which is something we have to do as well since that's what ends up on the users system) is orthogonal from that.

Packages might also be maintained "upstream first", by using same scheme as the upstream package (i.e. not streamlining our maintenance but instead zig-zagging between the numerous varying schemes used for each package in Debian).

which is fine since we can always drop our downstream for and if we maintain it in Debian we should also have a good packaging history on salsa. I think Debian's gnome team makes a good example here especially since Ubuntu bases their packaging on it, so it's very similar to what we do.

I disagree, however, that we should treat generated packages as merely "artifacts" because those are the very thing that ties us back to Debian.

I don't think this is true in 2021 in general. Most downstreams i encounter tie themselves more back via git than via the archive when it comes to the *development* workflow. I think it makes sense to keep the development process (and that's what mostly matters with upstream first as well) and the process of delivering software to the user separately.

I agree that there are gaps and ones that Debian tries to fill in since several years but I don't think that we're bound to that but rather that developing a good model for maintaining via git can help Debian in the long run.

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

I notice that https://tracker.debian.org/ links to patches from Ubuntu, for easy cherry-picking by Debian package maintainers.

I have never seen any Debian packaging aid listing downstream git branches/commits for easy cherry-picking by Debian package maintainers.

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 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:

If we want to do "upstream first" for packaging, we should align with what is done upstream in Debian. Debian uses Debian source packages as its reference source format (yes, some teams in Debian use git for preparing, but some don't and Debian has not yet chosen to alienate those who don't so we should neither).

...but sure, we can choose to not do "upstream first" for packaigng. Or we can choose to do "upstream first" only for that subset of Debian that comply with our streamlined way of working. I think that is a bad approach: I think that is not communicating to Debian that PureOS is prioritizing getting their work upstreamed into Debian.

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?

Yes.

Ideally we offer each and every single one of our patches (that are relevant for use outside of PureOS) as a bugreport with either a patch file attached or a link to a merge request (depending on how each upstream prefer proposals served to them).

More realistically, we should at least make our work available so that the differences from Debian is clearly visible in as close to Debian form.
Sure, we should then _also_ make the diff available in a form as close to upstream projects as possible - but that is more tricky because upstream projects has less of a standardized format across the board - i.e. really the "across the board" standard is called "file bugreport and/or provide merge request"

So what I am talking about here is for the cases where we fail to do the ideal of serving all our changes on silverplates to both Debian and upstream projects.

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?

You're mixing things here: since the debs are int the pureos archive (and should be) there's no problem applying the same pattern on https://tracker.pureos.net to the PureOS archive since that is offered there (e.g. at https://patches.ubuntu.com/libv/libvirt/libvirt_7.0.0-2ubuntu2.patch) is a debdiff of the source packages.

If we want to do "upstream first" for packaging, we should align with what is done upstream in Debian. Debian uses Debian source packages as its reference source format (yes, some teams in Debian use git for preparing, but some don't and Debian has not yet chosen to alienate those who don't so we should neither).

I don't think that's a requirement. We don't need to use the smallest common denominator, we don't to that with other projects we're contributing to upstream either (i.e. we use gitlab and issues there while kernel development prefers mailing lists). And as noted above source packages are still the refrence for what gets shipped (how would that work otherwise)?) but it shouldn't be where development focuses on. I don't know of a single team in Debian nowadays that works this way, also the downstreams i know about lookt at git (as noted above).

More realistically, we should at least make our work available so that the differences from Debian is clearly visible in as close to Debian form.

that doesn't contradict having the archive mostly as an artifact store. We still want to do policy conformant packaging etc.

More realistically, we should at least make our work available so that the differences from Debian is clearly visible in as close to Debian form.

Which can still be done (which is one of the reasons i brought up that we need tooling to see the delta between pureos and Debian multiple times). I clearly fail to understand your point here.

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

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

Please compare current subject with my more narrow suggestions at https://tracker.pureos.net/T1049#18871 which you didn't comment on.

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

No, this was specifically about updating downstream packages (which was the in the initial title btw ;) ). I have opened this issue here, because of the suggestion in T1048 to open an issue for the "meta discussion"

Please compare current subject with my more narrow suggestions at https://tracker.pureos.net/T1049#18871 which you didn't comment on.

Sorry, I had thought with the renaming that took place a few posts later that the question around the title had settled. I realize that even together with the OP some ambiguity remains.
Sorry for all the confusion that has ensued around the scope.

Changing the title to pureos: unclear how to best update downstream forks

Evangelos wrote:

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

Thanks. Yeah, your original subject was not so bad after all :-/

Guido wrote:

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?

You're mixing things here

Yes, I was rambling. Let me try clarify:

1. I am talking about the Debian standard for well-structured patches DEP-3 (not DEP-5)
2. Debian tracker currently link to a single dumb delta between the forked Ubuntu package and its Debian parent (not DEP-3 patches)
3. 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).

Guido wrote:

More realistically, we should at least make our work available so that the differences from Debian is clearly visible in as close to Debian form.

Which can still be done (which is one of the reasons i brought up that we need tooling to see the delta between pureos and Debian multiple times). I clearly fail to understand your point here.

I think changelog should be a log - i.e. only appended (not meshed).
Yes, that is a policy rule, not a best practice - a policy that does not exist in Debian because it has no parent and therefore is far less likely to run into the issue of how to represent fused multiverses.
No, statistics of current practice in PureOS won't change my thinking here.

I think that PureOS packages should not contain a full log of the history of PureOS development. I think that every time a package is re-synced with Debian then the changelog file should have have forking changes appended only. Continue to append on top for successive fork releases, but throw it all away and start over when re-syncing.

If I am mistaken and our changelogs are fine, then there is no issue to be addressed here (T1011 and T1012 are still relevant, but for other reasons than changelog files being flawed).

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

That's all fine and works with what with all ways of packaging we currently do in byzantium since that is DEP-3 compatible in the first place. From https://dep-team.pages.debian.net/deps/dep3;

2009-09-26: Modified structure to allow for 2 set of fields (the header and pseudo-header). Make Subject an alias of Description, From an alias of Author and Acked-by an alias of Reviewed-by. All those changes allow for a better compatibility with patches that are VCS changesets embedded in mails (notably those generated by git format-patch).

I'm not saying there's currently a lot of meta data being added apart from the topic/subject but that' not related to the way *how* downstream forks are prepared technically but a matter of adding that metadata manually once. But according to you definition above we can already tick that off.

Yes, that is a policy rule, not a best practice - a policy that does not exist in Debian because it has no parent and therefore is far less likely to run into the issue of how to represent fused multiverses.

It would need to *become* a policy rule, it isn't one already. I don't think this is a good idea though since merging changelogs keeps valuable information around (especially when *not* treating git as the focal point):

• which version were already synced into PureOS and *when* and by *whom*
• what adjustments were made back then (and ideally why)

and i don't think this would make it any harder for Debian to look at the diffs.

If I am mistaken and our changelogs are fine, then there is no issue to be addressed here (T1011 and T1012 are still relevant, but for other reasons than changelog files being flawed).

I don't think that changelogs currently match your expectation as is since many packages don't repeat the made changes in the topmost entry. But that again is not a result of the *way* the packages are prepared but (due to the lack of that being spelled out anywhere) not being by known by everyone atm. If this
is in the docs and reasonable (e.g. have a boilerplate like PureOS changes plus <whatever else is done> why not?

(PureOS changes would be s.th. like adjusted maintainer and vcs fields, ... we could also add a X-PureOS-Standards-Version` or similar so we can autovalidate that but that would be a bonus).

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

Thanks for the clarification . sorry that I was unclear.

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.

Concretely, I currently find changelogs of the following PureOS packages hard to decipher:

libhandy-1 1.2.0-1pureos1~amber1 https://source.puri.sm/pureos/packages/libhandy-1
libqmi 1.26.8-0.2~pureos0~amber1 https://salsa.debian.org/debian/libqmi
librem5-devkit-tools 0.0.15pureos0~amber0
modemmanager 1.14.12-0.1pureos1~amber1
phosh 0.8.1-1pureos1~amber1
gnome-calls 0.3.2-1pureos1 https://source.puri.sm/Librem5/debs/pkg-calls
libhandy-1 1.2.0-1pureos1 https://source.puri.sm/pureos/packages/libhandy-1
modemmanager 1.14.12-0.1pureos1
phosh 0.10.2-1pureos1
wlroots 0.12.0-1pureos0
wys 0.1.11-1pureos1

Here is the topmost changelog sections of the most recent of above packages:

modemmanager (1.14.12-0.1pureos1~amber1) amber-phone; urgency=medium

  * Backport to amber-phone

 -- Sebastian Krzyszkowiak <sebastian.krzyszkowiak@puri.sm>  Mon, 26 Apr 2021 05:32:28 +0200

modemmanager (1.14.12-0.1pureos1) byzantium; urgency=medium

  * Upload to byzantium

 -- Sebastian Krzyszkowiak <sebastian.krzyszkowiak@puri.sm>  Mon, 26 Apr 2021 05:31:00 +0200

modemmanager (1.14.12-0.1) unstable; urgency=medium

  * Non-maintainer upload.
  * New upstream version, bug fixes only, no new features.
    - MBIM:
      - Plug memleak in disconnection logic.
      - Don't fail IPv4v6 connection attempt if only IPv4 succeeds.
    - QMI:
      - Fix network registration cancellation logic with asserts disabled.

  [ Helmut Grohne ]
  * Annotate dbus dependency <!nocheck>. (Closes: #980827)

 -- Martin <debacle@debian.org>  Fri, 12 Mar 2021 18:09:44 +0000

modemmanager (1.14.10-0.1~pureos0~amber1) amber-phone; urgency=medium

  * New upstream version 1.14.10
  * d/patches: Drop already applied patch
  * d/patches: mm-base-bearer: Bump bearer stats update timeout from 30s to 5m

 -- Sebastian Krzyszkowiak <sebastian.krzyszkowiak@puri.sm>  Sun, 14 Feb 2021 09:03:47 +0100

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 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'm not debating that debian/changelog could be improved. I'm saying it's an orthogonal problem from whether one 'rebases' (aka redoes everything on each new version) versus a 'git merge'. For the changelog quality to improve it needs someone who *cares* to make a good suggestion that balances additional work with benefit (which can certainly by improved by automation). Suggesting summarizing remaining changes (minus changes that supposed to be there anyway like Maintainer: and Vcs-* field changes would likely be a good start.

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.

'm saying it's an orthogonal problem from whether one 'rebases' (aka redoes everything on each new version) versus a 'git merge'.

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 think comprehensible changelogs are directly tied to whether those changelogs are created by a) meshing two histories together or b) by treating one history as primary baseline and only adding on top of that any changes included from the other history.

Debian Policy already covers that all user-visible changes should be covered in changelog. Consequently, "summarizing remaining changes" either implies that those same changes are already covered buried deper down in a meshed history, or it is not up for discussion as it is part of Policy already.

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.

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.

If I understand correctly: It's orthogonal because we can fix up d/changelog when doing the release (so orthogonal because it can also be with the merge strategy).

Never having gone with the rebase strategy b) (so this might not be valuable insight) doing the merge strategy sounds like the easier path to me - as in: less work - even if having to manually clean up d/changelog.

So the question than would be: are both ways acceptable if they lead to the same result?

And if yes: Than I guess it "just" needs discussing (and I would believe this issue to be a good place for this discussion as well - but @jonas.smedegaard you probably know better ;) ) how a "good" d/changelog should look like?

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

are both ways acceptable if they lead to the same result?

Strictly speaking: Yes.

Any preparation style regardless of non-metadata contents of the changelog file is acceptable (obeys all "must" in Policy).
Debian Policy requires that the file exists and contains certain metadata, and recommends that it mentions changes (somewhere somehow - maybe meshed maybe as morse code):

Changes in the Debian version of the package should be briefly explained in this file

https://www.debian.org/doc/debian-policy/ch-source.html#debian-changelog-debian-changelog

Personally I expect a changelog file to contain changes as a log, with each timestamped section being successive to the previous section and the above quoted phrase applying to each section of the changelog file rather than the file as a whole.
That is just personal interpretation, however - anything goes, from a strict reading.

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

yes

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.

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.

But that doesn't have to matter in any way for the artifact that ends up in the archive. You could *even* discard the old changelog and just put an entry on top - not that i'd do so but one could. You could also do a pureos-merge-changelogs (in the spirit of dpkg-merge-changelogs that does that for you.

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?

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.

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.

But that doesn't have to matter in any way for the artifact that ends up in the archive.

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).
Sorry that I told you how you work or how your routines behave. I obviously cannot do that and you are right that (as an example only) preparation routines which includes e.g. "...and if changelog gets messed up then make sure to revert that change or roll back and redo with the changelog file excluded" can (with a stretch) be described as "orthogonal" to editing changelog files.

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.

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.

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.

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 mean releasable artifacts in the continuous delivery sense (https://en.wikipedia.org/wiki/Continuous_delivery which uses the term but doesn't give definition) (meaning the stuff that gets shipped).

Sorry that I told you how you work or how your routines behave.

I thought the whole point of this discussion is that we tell each other how things could work.

I obviously cannot do that and you are right that (as an example only) preparation routines which includes e.g. "...and if changelog gets messed up then make sure to revert that change or roll back and redo with the changelog file excluded" can (with a stretch) be described as "orthogonal" to editing changelog files.

That's not what i'm after. 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).

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.

I think the best way to reduce maintenance burden is to adopt a common model for how to handle downstream forks across PureOS so load can spread and contributors have an easier way to join than in Debian where it's hard to work cross teams due to different packaging practice. On the Librem 5 side with the switch to byzantium we have established a good common model on how to package for PureOS guided by:

• making our own software a downstream fork of Debian (so one don't have to think about how to apply a minimal fix so maintainership can spread)
• picking a common workflow based on what is done upstream in DebianOnMobile and Debian's GNOME team which makes it simple to cooperate with the (for us) most relevant parts of the Debian community based on git rather on debdiff+bts) plus being able to share with upstream (wlroots/GNOME/mesa/modemmanager/...) and making it simple for people from Debian/Mobian to work on both ends.
• picking a workflow that matches the parts of PureOS we've encountered by basically doing a git checkout pureos/byzantium && git merge debian/<version>. I learned in this issue that you maintain things in a different manner than the PureOS GNOME packages (and related packages that needed to be touched for migrations to happen) we've encountered.

This wasn't so well established for amber-phone (see e.g. sloppy packages, etc) which were good as a start but then resulted in issues *because* when you needed to work on a package you'd have a hard time to figure out what the relevant versions are). Hence I'd propose to use that pattern across PureOS where it makes sense and mark packages accordingly (we can tag repos in gitlab with e.g. a git-merge or git-rebase tag so it's obvious what pattern to apply). That said it would be good to have input from @mak and @jeremiah.foster here as well since it affects all of PureOS.

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 ;)

Apart from that I can only second what @guido describes (in the post directly above) as the current practices with respect to packages from the L5 dev team and also what I'm doing for Mobian f.e. (although there we don't care that much about d/changelog)

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

I agree that package preparation which does not touch changelog file is orthogonal to authoring the changelog file.

I disagree that package preparation which alters changelog file is orthogonal to authoring the changelog file.

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.

I expect package changelogs to summarize release changes, and I think I am not alone (regardless of the possibility that GNOME package maintainers collectively have a different view on changelogs).
This is not nitpicking: It is really bad if I or our users cannot rely on package changelogs to summarize release changes.

So no, my frustration is not with tools per se, it is with authoring. I just speculate that authoring of frustrating changelog files might involve certain workflows and tooling.

I think the best way to reduce maintenance burden is [...]

I perfectly agree - for that more narrow view on the matter here.

My point is that best practice involves other factors than only reducing maintenance burden.

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 consider best practice for updating downstream forks is an "upstream first" workflow treating parent changes canonical, applying still-relevant fork changes on top of the canonical part.
Such preparation workflow results in an "upstream first" change graph, which is beneficial for others reusing the code. That well-structured change graph also helps authoring of the changelog file (i.e. instead of looking at authoring of changelog file as orthogonal to preparing the package release, the task of updating the changelog file is mostly a matter of delinearizing topmost part of the change graph e.g. using gbp dch --since <fir-relevant-commit>.

Using git lingo, what I consider best practice for updating downstream forks is to rebase forked changes onto newest parent release (not simply merge fork and parent together without preserving integrity and priority of parent changes).

For concrete implementation see T1012#18940, and please discuss implementation details there, not here.

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.

Then please suggest a documentation update. I just think most people aren't aware and since it seems to matter to you the most you should act on it and i have confidence we can improve that in the future.

My point is that best practice involves other factors than only reducing maintenance burden.

I can certainly imagine other relevant factors but it would here too be best to spell those out in a concrete documentation update proposal. There are factors that can easily outweigh this while others don't.