Feature #14575

Write technical design doc for Additional Software

Added by Anonymous 2017-08-30 16:21:24 . Updated 2018-11-12 12:57:24 .

Status:
Resolved
Priority:
Urgent
Assignee:
Category:
Target version:
Start date:
2017-08-30
Due date:
2018-03-15
% Done:

100%

Feature Branch:
master
Type of work:
Contributors documentation
Starter:
Affected tool:
Additional Software Packages
Deliverable for:
299

Description

Due: February 28th 2018 (B2).
Probably to be done during the GUI and UX sprint.


Subtasks


History

#2 Updated by Anonymous 2017-08-30 16:24:31

  • Deliverable for set to 299

#3 Updated by BitingBird 2017-08-30 17:11:35

  • Target version set to 2018

#4 Updated by Anonymous 2017-09-04 16:51:26

  • Affected tool set to Additional Software Packages

#5 Updated by Anonymous 2017-09-07 08:29:48

  • Target version changed from 2018 to Tails_3.6

#6 Updated by alant 2018-02-05 13:41:48

  • Due date changed from 2018-02-28 to 2018-03-15
  • Target version changed from Tails_3.6 to Tails_3.7
  • Blueprint set to https://tails.boum.org/blueprint/additional_software_packages/gui

Technical design doc is being drafted in the blueprint at https://tails.boum.org/blueprint/additional_software_packages/gui. It will be finalised after our code sprint during march.

Inspiration: https://tails.boum.org/contribute/design/persistence/

#7 Updated by bertagaz 2018-05-10 11:09:24

  • Target version changed from Tails_3.7 to Tails_3.8

#8 Updated by intrigeri 2018-06-26 16:28:00

  • Target version changed from Tails_3.8 to Tails_3.9

#9 Updated by alant 2018-07-28 17:48:20

  • Status changed from Confirmed to In Progress
  • % Done changed from 0 to 50
  • Feature Branch set to feature/14594-asp-gui

See contribute/design/additional_software_packages.mdwn.

#10 Updated by Anonymous 2018-08-07 13:43:47

  • QA Check set to Dev Needed

alant wrote:
> See contribute/design/additional_software_packages.mdwn.

This file is not present in feature/14594-asp-gui nor master. So I cannot review it.

#11 Updated by Anonymous 2018-08-07 13:44:28

  • Target version changed from Tails_3.9 to Tails_3.10.1

I’m fine with postponing this part to 3.10.

#12 Updated by alant 2018-08-09 17:40:16

u wrote:
> alant wrote:
> > See contribute/design/additional_software_packages.mdwn.
>
> This file is not present in feature/14594-asp-gui nor master. So I cannot review it.

Yes it is :

https://git.tails.boum.org/tails/tree/wiki/src/contribute/design/additional_software_packages.mdwn?h=feature/14594-asp-gui

#13 Updated by alant 2018-08-09 17:40:37

  • Assignee deleted (alant)
  • QA Check changed from Dev Needed to Ready for QA

#14 Updated by Anonymous 2018-08-19 11:05:53

I must have pulled from another git repo accidentally.

#15 Updated by Anonymous 2018-08-19 11:20:27

  • Assignee set to intrigeri
  • QA Check changed from Ready for QA to Pass

I’ve polished this a bit in 297fd54fc1676ea83a1c73f529858f9b9a3350ec.

Intrigeri: I’m not sure what to do to get this merged?

#16 Updated by Anonymous 2018-08-19 11:20:39

  • Status changed from In Progress to Fix committed

#17 Updated by intrigeri 2018-08-19 12:16:01

  • Status changed from Fix committed to In Progress
  • QA Check changed from Pass to Ready for QA

> Intrigeri: I’m not sure what to do to get this merged?

This :)

#18 Updated by intrigeri 2018-08-20 09:01:34

I’ve merged the branch up to commit:297fd54fc1676ea83a1c73f529858f9b9a3350ec. Note that Alan is using the exact same branch to push WIP stuff that’s not ready for merging, so we’ve been lucky you’ve pushed your changes before he did so I could merge them. In the future I suggest using different branches for different kinds of work that has a different review/merge cycle :)

I’ll now take a quick look at the design doc to see if it’s up to our standards.

#19 Updated by intrigeri 2018-08-20 09:18:00

  • Assignee changed from intrigeri to alant
  • QA Check changed from Ready for QA to Dev Needed
  • Feature Branch deleted (feature/14594-asp-gui)

It looks good!

  • wiki/src/contribute/design/persistence.mdwn already had a section about ASP. Please de-duplicate and point to the new page from there (it’s currently not referenced anywhere).
  • “design documentation” in the page title is not consistent with the rest of our design doc (and arguably duplicate info anyway)
  • Please now use a dedicated branch for this work so the various things you’re working on don’t block each other.
  • Some of the text paraphrases very precisely the implementation in a low-level way, which will be hard to keep up-to-date. Better stick to high-level descriptions of the general design, with pointers to the up-to-date code.
  • A few broken links, look for config/chroot_config/ and test your links before the next round of review :)

#20 Updated by alant 2018-08-26 13:22:46

  • Feature Branch set to bugfix/14575-asp-design-doc

#21 Updated by alant 2018-08-26 14:07:11

  • Assignee changed from alant to intrigeri
  • QA Check changed from Dev Needed to Info Needed

I belive I fixed everything you suggested but:

> * Some of the text paraphrases very precisely the implementation in a low-level way, which will be hard to keep up-to-date. Better stick to high-level descriptions of the general design, with pointers to the up-to-date code.

I simplified one item, but I don’t see how to cut more withour removing references that I find useful to understand hos it works and especially what files to look at. Examples?

#22 Updated by intrigeri 2018-08-30 04:45:59

> I simplified one item, but I don’t see how to cut more withour removing references that I find useful to understand hos it works and especially what files to look at. Examples?

Sure. I’ll look into this during the 3.10 cycle.

#23 Updated by intrigeri 2018-09-10 09:25:38

  • Assignee changed from intrigeri to alant
  • % Done changed from 50 to 60
  • QA Check changed from Info Needed to Dev Needed

alant wrote:
> I belive I fixed everything you suggested but:
>
> > * Some of the text paraphrases very precisely the implementation in a low-level way, which will be hard to keep up-to-date. Better stick to high-level descriptions of the general design, with pointers to the up-to-date code.
>
> I simplified one item, but I don’t see how to cut more withour removing references that I find useful to understand hos it works and especially what files to look at. Examples?

Sure, here are bits I think should not be in such a document:

  • is `WantedBy=desktop.target`
  • if the configuration file […] is not empty
  • It is a oneshot service
  • the bits about 99-zz-install-ASP-DPKG-hooks
  • I’m stopping here :)

See what I mean?

Other than that:

  • I’ve merged the current branch into master because it’s clearly better than what was there.
  • missing word in using options prevent questions?

#24 Updated by intrigeri 2018-10-24 17:03:40

  • Target version changed from Tails_3.10.1 to Tails_3.11

#25 Updated by Anonymous 2018-10-31 15:59:38

I cannot find bugfix/14575-asp-design-doc. Please repush this branch.

#26 Updated by Anonymous 2018-10-31 15:59:51

  • Priority changed from Normal to Urgent

#27 Updated by Anonymous 2018-10-31 16:16:41

  • Feature Branch changed from bugfix/14575-asp-design-doc to master

Ah sorry, I see now that this was actually already merged into master.

#28 Updated by alant 2018-11-09 11:48:50

  • Assignee deleted (alant)
  • % Done changed from 60 to 80
  • QA Check changed from Dev Needed to Ready for QA
  • Feature Branch changed from master to bugfix/14575-asp-design-doc

> Sure, here are bits I think should not be in such a document:
>
> * is `WantedBy=desktop.target`
> * if the configuration file […] is not empty
> * It is a oneshot service

I simplified this.

> * the bits about 99-zz-install-ASP-DPKG-hooks

I can’t remove this one without removing the refefence to this file which is useful for future reference/mainteners.

> * I’m stopping here :)
>
> See what I mean?
>
Not really I admit.

> Other than that:
>
> * missing word in using options prevent questions?

Fixed.

#29 Updated by Anonymous 2018-11-09 12:22:29

  • Assignee set to alant

@alan, thanks for looking into this.

The point intrigeri is making is that it’s not useful to maintain code snippets in the code and in the technical design doc, because the code might change and then the design doc will be outdated.

So the idea is to paraphrase what the code is supposed to do.

#30 Updated by Anonymous 2018-11-09 12:25:09

  • Feature Branch changed from bugfix/14575-asp-design-doc to master

#31 Updated by Anonymous 2018-11-09 12:25:43

@alant: i don’t see where you fixed that by the way. Please let us know which branch to review.

#32 Updated by alant 2018-11-09 16:20:10

  • Assignee deleted (alant)
  • Feature Branch changed from master to bugfix/14575-asp-design-doc

> So the idea is to paraphrase what the code is supposed to do.
I think it’s done as much as possible without removig pointers.

I forgot to push, which I did now in the mentionned branch.

#33 Updated by Anonymous 2018-11-11 12:54:53

  • Assignee set to intrigeri
  • Feature Branch deleted (bugfix/14575-asp-design-doc)

Thanks, I’ve merged this into master. I’m fine with the proposed changes. @intrigeri: want to have another quick look?

#34 Updated by Anonymous 2018-11-11 12:55:25

  • Feature Branch set to master

#35 Updated by intrigeri 2018-11-12 12:57:24

  • Status changed from In Progress to Resolved
  • Assignee deleted (intrigeri)
  • % Done changed from 80 to 100
  • QA Check changed from Ready for QA to Pass

Good enough. I’m still wary that this doc will become outdated wrt. the actual implementation but whatever, we’ll see and if that happens, I’ll drop the implementation details myself.