docs: Add small how/why and user tutorial

[Melkor333]

I thought writing some user docs is the best way to repeat what I just learned and analyzed :)

Some features are still ignored and publish is not even properly started, but we'll get there.

[Melkor333]

@ganwell I've tried to get the reasoning for certain design decisions here. But I struggle to see how to go forward. There are a few untouched topics (ie snapshot merging, publish from publish) and the publish section is generally very short (is there more to it? 🤔 ). I think it's OK to not have all use cases here but e.g. in an additional howto's documentation providing snippets similar to the test cases. Or just mention them in a configuration file reference. What do you think?

[rhizoome]

This looks great! Thank you very much. I added some ideas to extend the documentation.

[rhizoome]

background

What I am saying here adds nothing new to your text. It is just the view from the application instead the user. Feel free to incorporate anything you think helps:

• pyaptly reads the current-state of aptly
• it will create all commands needed to create the should-state based on the current time
  • commands that create something that already exists in the current-state will be discarded (example)
• it will resolve the dependencies into a command-tree
  • while resolving it will again check the state to see if the thing already exists
• it will then execute the commands
  • if one command in the tree fails dependant commands will not and cannot be executed

this also ties into an issue where we are currently using pyaptly wrong (I do not know the details of how we are using it, I am inferring from questions I got). also take this with a grain of salt, I haven't been using pyaptly for a long time, maybe something slipped my memory.

• there should only be one pyaptly cronjob: Calling a script doing all operations. Since it won't redo anything this is safe and efficient
  • the job has to be called in the smallest interval needed (week if there is only a weekly policy, daily if there is a daily policy)
  • this prevents snapshots from not being available when publish is called (I assume we currently have a snapshot-cronjob and a publish-cronjob)
• if there is overlap in the cronjobs, the second job should probably not run (this is a feature we could add to pyaptly: some kind of "lock"-ckeck), currently this has to be scripted
• if there chronic overload of pyaptly (because of the missing cleanup-features), pyaptly should run in a loop with a sleep-statement (to prevent overheating if pyaptly fails fast)

Of course on the point about create one script is interesting of this documentation. I just added the other points, because it came to my mind.

[rhizoome]

• maybe you could cover %T for referring to snapshots and archive-on-update. See
• or do the same comparison to the aptly commands as you did above. (you could make use --info to see what commands are generated, if you use dry-run, you could change to config, without having to revert stuff all the time)
• there is also the merge and the timestamp feature. See

digging into these features

• the timestamp basically means n-th oldest timestamp. it is called back_ref in the code
• merge is a snapshot feature, but a user might think of it in publishing, because only there it makes sense. See
• archive-on-update seems to be meant to document when exactly a publish was changed, as it might have implications on policy or bugs discovered (before/after a change in publish). See

[rhizoome]

@Melkor333 I'd like to push this. Maybe you can do another iteration with my inputs later.