Qubes 4.0-rc3

[heartsucker]

Hi everyone

I'm testing out Qubes 4.0-rc3 and need to set up VPM VMs for different
domains. I'm attempting to follow the instructions listed here:
https://www.qubes-os.org/doc/vpn/

The screenshots deviate significantly from what I'm seeing in my
installation, namely that there doesn't seem to be any thing that
resembles a ProxyVM. I looked in the qubes-doc repo for update docs, but
it looks to be the same as what's currently live.

Is there a guide or blog post about setting up VPN VMs or ProxyVMs in
the 4.x series?

Danke.

-h

[Kushal Das]

In simple steps, create an app-vm, click on the checkbox saying it
provides network,
open the configuratin, and add `network-manager` in the services. This
will give you
a nm-applet, click on it and add a vpn normally in the UI. I am using
Fedora 26 for
my vpn vms.

I will write down a blog post tomorrow along with screenshots about
this. If you want the command
line options, I have one old blog post[1].

[1] https://kushaldas.in/posts/network-isolation-using-netvms-and-vpn-in-qubes.html

Kushal
--
Staff, Freedom of the Press Foundation
CPython Core Developer
Director, Python Software Foundation
https://kushaldas.in

[Chris Laprise]

This is basically the same directions as in the Qubes VPN doc, except
the user chooses "provides network" when creating the VM. That is the
difference.

The scripted method in the doc is better because it fails closed and
protects against leaks, but requires an additional step in R4.0:

sudo ln -s /rw/config/qubes-firewall-user/script
/rw/config/qubes-ip-change-hook

I also have a download-able project that makes the scripted/antileak
setup fairly simple in Qubes R4.0:

https://github.com/tasket/Qubes-vpn-support/tree/qubes4


--

Chris Laprise, tas...@posteo.net
https://github.com/tasket
https://twitter.com/ttaskett
PGP: BEE2 20C5 356E 764A 73EB 4AB3 1DC4 D106 F07F 1886

[Tom Zander]

On Wednesday, 10 January 2018 18:32:39 GMT Chris Laprise wrote:
> I also have a download-able project that makes the scripted/antileak
> setup fairly simple in Qubes R4.0:

Please consider updating the docs repo with this :-)

I poked the Qubes guys about providing a separate dir on the website to make
it clear what is 3.x and what is 4.x specific, but they stated we should
instead put notices about exceptions in the document pages.

So I guess things like ProxyVMs should be mentioned to be old and AppVM is
the new.
--
Tom Zander
Blog: https://zander.github.io
Vlog: https://vimeo.com/channels/tomscryptochannel

[Chris Laprise]

On 01/10/2018 01:53 PM, 'Tom Zander' via qubes-users wrote:
> On Wednesday, 10 January 2018 18:32:39 GMT Chris Laprise wrote:
>> I also have a download-able project that makes the scripted/antileak
>> setup fairly simple in Qubes R4.0:
>
> Please consider updating the docs repo with this :-)
>
> I poked the Qubes guys about providing a separate dir on the website to make
> it clear what is 3.x and what is 4.x specific, but they stated we should
> instead put notices about exceptions in the document pages.
>
> So I guess things like ProxyVMs should be mentioned to be old and AppVM is
> the new.
>

Of course, there is very little R4.0 documentation at this point. There
is also a blocking issue that leaves the behavior of firewall scripts
undetermined for now; The update for the VPN doc will be done when that
issue is closed.

Yes, "AppVM supplying networking" would be a replacement term for ProxyVM.

I prefer a separate area for R4 docs as well. The command line tools and
GUI have changed enough to warrant it, IMHO, and its off-putting to be
faced with documenting a lot of "do-this-or-that".

[Connor Page]

The official templates use nftables so shouldn’t be mixed with iptables. I didn’t have time to learn about nftables, so just removed nftables package from debian 9 template. YMMV.

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On 2018-01-10 12:53, 'Tom Zander' via qubes-users wrote:
> On Wednesday, 10 January 2018 18:32:39 GMT Chris Laprise wrote:
>> I also have a download-able project that makes the scripted/antileak
>> setup fairly simple in Qubes R4.0:
>
> Please consider updating the docs repo with this :-)
>
> I poked the Qubes guys about providing a separate dir on the website to make
> it clear what is 3.x and what is 4.x specific, but they stated we should
> instead put notices about exceptions in the document pages.
>

That's not exactly right. Please see:

https://www.qubes-os.org/doc/doc-guidelines/#version-specific-documentation

Specifically:

"In cases where a documentation page covers functionality that differs
considerably between Qubes OS versions, the page should be subdivided
into clearly-labeled sections that cover the different functionality in
different versions."

In other words, do not just add notices in the text about exceptions.
Instead, make clearly-labeled sections for 3.x and 4.x so that users
can easily find the right information no matter which version of Qubes
they're using.

> So I guess things like ProxyVMs should be mentioned to be old and AppVM is
> the new.
>

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAlpW3QcACgkQ203TvDlQ
MDBFPxAAh14g5TA1GxOnWL+uBQIJLVgz63/j18j5hWD6lA9VaqGZkYm6yd1Ctd2E
OoGVqbIdPtXnlB53E25tCSn0+iRiFeZ+XfmdMGxP8UQ96Cdl/dc/JZQeMMpcuGbH
17HdtXhNGPkg1g0/kG04Eggc43ZdjcBGn94Rv3InPGJiLUQutPXrS6g3kp+N6OL4
iH8Vn/P8PUUlGHfuhMjRAxQPlTzIPt6DA/eivjRDZ3IR6Zw/LCFxyZ6IZf5Cxdet
gX+5TIrkmDBc/MqkW+xQWdYYfQao0hwqhWRXmrNMXaG4Q/yTC+/GmesY+3RU7T/7
tMPPcPjZ+I0MjDq81YSz/C7bcwgE5k6jLplUmZV43xHM2+JLPWGQf0d0Qf//VdJr
Y9oASEPbOoSweOAGRd7n7oNaqPgarGRvPdRIecDckXAK25mVed/da7FZZ1EL+HKc
ij/Zpw/X9ZKG3XbCvUlYOPkExlerIHvj6rZC4PuGYB45K4nxKELoGEIJakjHkSel
VPOPiZBPwUqSCtwNox5APivbpM8Jm5oKEIAm768KwHhHZC+WZQq/ir2j9Fcxqb3O
fg5NgNFaJ0WsIs9hAZAF1ALC7focKsB2wre8qy0vRKzYuhD3FRCPcuOeGkW6eCA7
BNOvbDYhMiLDyXnRnlO3/CVHqnioWWEAUP7pFrxtpp+xTdJBbRo=
=cxLl
-----END PGP SIGNATURE-----

[Tom Zander]

On Thursday, 11 January 2018 03:42:11 GMT Andrew David Wong wrote:
> On 2018-01-10 12:53, 'Tom Zander' via qubes-users wrote:

> > I poked the Qubes guys about providing a separate dir on the website to
> > make it clear what is 3.x and what is 4.x specific, but they stated we
> > should instead put notices about exceptions in the document pages.
>
> That's not exactly right. Please see:

..

>
> In other words, do not just add notices in the text about exceptions.
> Instead, make clearly-labeled sections for 3.x and 4.x so that users
> can easily find the right information no matter which version of Qubes
> they're using.
>
> > So I guess things like ProxyVMs should be mentioned to be old and AppVM
> > is the new.

Ok, I am having problem seeing your solution and my explanation of it as any
different, in practice.
Maybe I'm missing the obvious, I'm just not seeing it.

In this specific case of the VPN page. https://www.qubes-os.org/doc/vpn/
* in v.4 there is no "NetVM".
* There is no "ProxyVM"
* The create qubes screenshot is considerably different.
* adding 'meminfo-writer' and 'network-manager' are not needed (AFAIK).
* does not use iptables anymore.

Ok, going to stop now. I got to half the page and some 80% of the text and
screenshots are wrong for v4.

How would you solve that in line with the QubesOS policy?

[Unman]

The difference is between this style:

You can attach a disk image to a qube using qvm-block :
qvm-block -A <target> [qube:]<file>
(This syntax is not available in 4.0)

and this:
3.0
You can attach a disk image to a qube using qvm-block :
qvm-block -A <target> [qube:]<file>

4.0
You cannot attach a disk image to a qube using qvm-block.


The advantage of using labelled sections is that it should be easier
for users to find the material relevant to the version they are using.
Also, that once 3.0 is retired, it will be simple to remove the 3.0
relevant material, rather than filleting our bits from each page.

On the VPN case your own comment confirms that it would be better to
provide a separate section, rather than trying to put "exceptions" in to
the existing text.

[Chris Laprise]

At least no section repetition for the scripts should be necessary. But
doing this for the dialogs still adds a lot to an already long doc.

I feel that, apart from making some docs look deceptively long and less
readable, the most significant downside to melding 3.x/4.x instructions
together would be to discourage contributions from users. It makes the
thought of every potential edit seem like a slog through extra markdown,
and many will think "I don't have time to install 3.2 to write up that
version".

[Chris Laprise]

On 01/10/2018 03:47 PM, Connor Page wrote:
> The official templates use nftables so shouldn’t be mixed with iptables. I didn’t have time to learn about nftables, so just removed nftables package from debian 9 template. YMMV.
>

Hmmm, I was just thinking how Qubes' own guest scripts still use
iptables even in fedora-26.

IIUC, iptables and nft are two different interfaces to netfilter. I
don't know if it really matters, at least for the R4.0 window. I'd
prefer to put the syntax change (for docs) off until a later release.

[Tom Zander]

On Thursday, 11 January 2018 18:16:04 GMT Unman wrote:
> On the VPN case your own comment confirms that it would be better to
> provide a separate section, rather than trying to put "exceptions" in to
> the existing text.

Thank you for explaining that unman, much clearer indeed.

While I agree on the general statement above, I feel its not the best
solution in this case where 4.0 have massive changes in all layers of the
technology.
In many cases the about half of the text will be duplicated between the 3.2
and the 4.x sections, albeit with major changes.
This will not help the reader much.
More importantly, I fear that the new users (potential contributors) that
have not used 3.2 will have a hard time deciding what to do with information
that clearly doesn't represent the current state of technology.

Asking people to put a lot of effort into reformatting documentation that
may or may not actually be useful to anyone using an older version is a big
ask in a volunteer project.

I personally prefer the solution where a git repo is cloned for 3.2 as
"legacy" which is then attached to the website under a subdirectory and
people can edit that for maintainance and fixes.
http://qubes-os.org/doc/3/
or somesuch.

The majority of changes would then be in the 'master' branch which people
can edit and they can add references to the github issues concerning known
bugs. We can mark known issues with the pages like the VPN one I described
and people reading the docs will actually be aware of pitt-falls.

In my opinion there is only one thing worse than no documentation, it is
official looking documentation that is wrong.

> Also, that once 3.0 is retired, it will be simple to remove the 3.0
> relevant material, rather than filleting our bits from each page.

This would be even better, if qubes ever wants to they can just remove the
subrepository.


What do others think?

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Is it bad for a doc to be long when it's immediately obvious which
half you can ignore because it's not the version you're using?

> I feel that, apart from making some docs look deceptively long and less
> readable, the most significant downside to melding 3.x/4.x instructions
> together would be to discourage contributions from users. It makes the
> thought of every potential edit seem like a slog through extra markdown,
> and many will think "I don't have time to install 3.2 to write up that
> version".
>

I don't understand. Why would this be the case? If you want to make a
small edit that pertains only to 4.0, you can simply make that small
edit in the 4.0 section, or add such a section if one doesn't yet
exist, which would only be a few extra characters. A 4.0 user who
wants to add some true fact about 4.0 to the docs doesn't even have to
think about 3.2, much less install it.

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAlpYK/4ACgkQ203TvDlQ
MDCO5g//X83cUUXJ+wC3PbbyXFcPnryX+po4wpscNtzjN9XEY3isKFpbzWph2iPD
E365gKrhZCPn5Rmcum2cTtEdtoP9AOzMTgaZGF8xkkq0XZmZsAppAbfEhNHHkcdT
1WMkGvnYsFmt+Q8m0EgRmuKsU+STyrm7b5ZGI2ilweqYyBRMNtbOQl+PaPX4A6dY
snHECZ7yZ9wLQGPJaVV7uxirxEnxq0jtc55jbEou6Pk3yMY3hCKeYzlTi9DMJ8hh
kuVVoH58dXu0R2C7CunpfZ46Z5PRiV3+8Tm5pRBMZHhEomKLIv9VkVZ2JBw9kbmj
FMOmk3XTsYZAFfYpmlKM9yNM0s9ZrHniCZMA6cTlZpqVFlGnsZGso3fqapBayijy
zuGcwYPa0dIw+eWqnz+wbfOPrBxV5U0O3y9hM7HO6RDG0nrBLHO2QKO+wUugCmX0
DkKRkmN5a0oueIDf2DAdeXGLCBnSy9zdcyrtXDtbDh7Rlwg9ko9f82ZZoZM6alIb
7J0J73el8KjLiJEtJPu8vGTYq6EIhoflvXDMzXwd/49Oeoqb7MeJ7qo14iad3bp0
nu3z2n9MSa2VP71p6db9aKOGYb+chHMA6l09vd/Fab4mIQVl/LA2DpEDFV7wOgwv
VJ/Q5VuidOZ0lxw7jpmmeqFC07g98qdxnbP+TXVCsio2JbhcbZA=
=w/TA
-----END PGP SIGNATURE-----

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On 2018-01-11 16:11, 'Tom Zander' via qubes-users wrote:
> On Thursday, 11 January 2018 18:16:04 GMT Unman wrote:
>> On the VPN case your own comment confirms that it would be
>> better to provide a separate section, rather than trying to put
>> "exceptions" in to the existing text.
>
> Thank you for explaining that unman, much clearer indeed.
>
> While I agree on the general statement above, I feel its not the
> best solution in this case where 4.0 have massive changes in all
> layers of the technology.

A lot of changes, sure, but I wonder whether there are more
similarities than differences overall (thinking about fundamental
things like the use of Xen and TemplateVMs).

> In many cases the about half of the text will be duplicated
> between the 3.2 and the 4.x sections, albeit with major changes.
> This will not help the reader much.

Why is that? Just because many docs will be longer, since they'll have
a section for 3.2 and a section for 4.0?

> More importantly, I fear that the new users (potential
> contributors) that have not used 3.2 will have a hard time
> deciding what to do with information that clearly doesn't represent
> the current state of technology.
>

Why will this be a problem? If the section is clearly labeled "Qubes
3.2," but they use 4.0, are you concerned that they won't realize the
section doesn't apply to them? If they can't make that distinction,
though, why expect them to be any more successful at distinguishing
between two sets docs?

> Asking people to put a lot of effort into reformatting
> documentation

It shouldn't require much effort. In most cases, all you have to add
is `## Qubes 3.2` above the existing documentation, shift the rest
of the headers down one by adding a `#` in front of each one, then add
`## Qubes 4.0` above the 4.0 content you want to add. It might be
slightly trickier if the current headings use the underlining syntax.
This requires basic familiarity with Markdown, but that's already
required for most doc contributions. Only one person has to do this
for each document, and many documents will not even require this
because the content applies to both 3.2 and 4.0.

> that may or may not actually be useful to anyone using an older
> version

Wait, why wouldn't 3.2 documentation be useful to anyone using 3.2?
The majority of users are on 3.2 right now:

https://www.qubes-os.org/statistics/

And 3.2.1 will be supported for a full year after the stable release
of 4.0:

https://www.qubes-os.org/news/2016/09/02/4-0-minimum-requirements-3-2-extended-support/

> is a big ask in a volunteer project.
>> I personally prefer the solution where a git repo is cloned for
>> 3.2 as
> "legacy" which is then attached to the website under a
> subdirectory and people can edit that for maintainance and fixes.
> http://qubes-os.org/doc/3/ or somesuch.
>

If I understand this proposal correctly, all the current documentation
would initially exist in the 4.0 documentation set. But a lot of it,
as you've pointed out, only applies to 3.2. So, who's going to go
through and remove all the content that no longer applies in 4.0?
That's a lot more difficult than formatting a few headings, so it
strikes me as a much bigger ask.

Alternatively, we could start with an empty directory for 4.0. Then
no one has to sort through all the 3.2 documentation to see what still
applies. But now we have an even bigger problem: *all* the
documentation has to be written (or selectively copy/pasted)! This
seems like an even bigger ask the previous one.

Is there some third way you have in mind that I'm missing?

> The majority of changes would then be in the 'master' branch which
> people can edit and they can add references to the github issues
> concerning known bugs. We can mark known issues with the pages
> like the VPN one I described and people reading the docs will
> actually be aware of pitt-falls.
>

You can (and are encouraged) to do exactly this under the current
system. There's nothing stopping you from doing this, and there are a
lot of examples where this has already been done in the existing
documentation.

> In my opinion there is only one thing worse than no documentation,
> it is official looking documentation that is wrong.
>

I agree, but I don't see why having clearly-labeled sections where
there are version differences would result in this. If there's some
official documentation in a section called "Qubes 3.2," it's not
"wrong." It applies to 3.2.

Maybe the concern is that, *before* someone gets around to adding the
"Qubes 3.2" heading, a 4.0 user will see it and be misled. That's a
legitimate concern, but how would your alternative proposal avoid it?
If we simply clone the documentation into two separate sets -- one for
3.2 and one for 4.0 -- we have the exact same problem. The 4.0 clone
still has stuff in it that's only true in 3.2, and until someone gets
around to deleting it, a 4.0 user who sees it could be misled. Am I
missing something here?

>> Also, that once 3.0 is retired, it will be simple to remove the
>> 3.0 relevant material, rather than filleting our bits from each
>> page.
>
> This would be even better, if qubes ever wants to they can just
> remove the subrepository.
>
>
> What do others think?
>

If there turn out to be significant, compelling reasons to make
completely separate sets of docs (one for 3.2 and one for 4.x), of
course I'd be happy to do that. We should weigh the costs and
benefits, and choose whichever system is best. From a maintainability
perspective, it seems simpler and easier just to have a single set of
docs, and that's what Qubes has always had, so that's why it's the
default system right now. That's not set in stone, but I think an
alternative system should deliver significant benefits for it
be worthwhile for us to move from the default system. So far, it seems
like the objections to sticking with the default system and simply
having separate sections within the existing docs rest on
misunderstandings about how that system would work, but I'd be
happy to be convinced otherwise. :)

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAlpYN1sACgkQ203TvDlQ
MDD2AxAAnPjscltdFLPYVZTapKJqiUiusiaeLdKaEDYUPRJzFJjovyL0cpzT0hFW
o3x0ob6UTZNdy4ptpjn7mT3hYkzIL9zYatZfCdPIOnmzLVAZOSkCs0vwjjFE/U0N
LGaU7CRWYcTAvGDM8QlF3JU8bAF24HUSDENpNBcluMWv19PHCshZpThKC4TwfWSH
JdAoc8GBYfp3KagDAZab3p1XiPRLn2ZrCPTMpj4H1cSErhUJ1dUSOu10C9gu3jiB
eaa/9tsqoEQZpwP0PE9NsIjNdNOnKVav0+1nHOU4cRiBWE/NTe8nA6vsW8P1gWOR
VCRpB6upwYvv42NYIXuWBJEJw1wHIFiF44sS/0SRG58QboXVik1jTnjBQqRQ7z1s
oRtTUsvoUyy5KP/5v4ODnlJ9LE64iHcXbZj2H00sSHSspHBOdzlJKPLr8W8ZhZ2M
riDVUjPN+0iHUMBXrEfsyNBY+Wdk+7f3XI/mrWJVW0BIDPQOWuRa5QBk2RGNHXJP
utC6yXlQK0T4u7CedEj8yp6FNW94N0fOjL1y1prSLZ6kbK+emfDD2gMYozO585u5
MOAkLujFv81MhI8EicuzEWeDRKlNIRNyqwdo/AG9yvq4cizzWIh51PXKMDEpjDBa
FPP9wg34Vie2svD/SK7WghJgguLrYT3uM3z3M7HyPclqcFH92Lg=
=ANlq
-----END PGP SIGNATURE-----

[Chris Laprise]

On 01/11/2018 10:31 PM, Andrew David Wong wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA512
>
> On 2018-01-11 14:41, Chris Laprise wrote:
>>
>> At least no section repetition for the scripts should be necessary. But
>> doing this for the dialogs still adds a lot to an already long doc.
>>
>
> Is it bad for a doc to be long when it's immediately obvious which
> half you can ignore because it's not the version you're using?

Not necessarily for a reader, except in the case where the instructions
are long to begin with and the reader happens to scroll into the section
for a different version... without a floating page element that always
keeps the heading visible, the reader might inadvertently mix directions
from the two version-sections.

>
>> I feel that, apart from making some docs look deceptively long and less
>> readable, the most significant downside to melding 3.x/4.x instructions
>> together would be to discourage contributions from users. It makes the
>> thought of every potential edit seem like a slog through extra markdown,
>> and many will think "I don't have time to install 3.2 to write up that
>> version".
>>
>
> I don't understand. Why would this be the case? If you want to make a
> small edit that pertains only to 4.0, you can simply make that small
> edit in the 4.0 section, or add such a section if one doesn't yet
> exist, which would only be a few extra characters. A 4.0 user who
> wants to add some true fact about 4.0 to the docs doesn't even have to
> think about 3.2, much less install it.

If they don't have to think about 3.2, that's fine. But I'd expect
queries/requests for "3.2 version" would appear in the PRs about some
new fixes, info or approaches the users are trying to introduce into the
document(s).

Making an edit "that pertains only to 4.0" isn't going to be the mental
context of the user-contributor in most cases. They will just have new
info that they are unsure whether it applies to 3.2 (or if it does,
how). And I'm sure even advanced users will be feeling the uncertainty
and friction before long.

Tom Zander makes some good points, too.

OTOH, I don't want to belabor the issue -- and I'm far from certain
anyway, this is about psychology.

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Wouldn't the same problem apply if there were two sets of docs? They'd
have to make the same decision about whether to add it only to the 4.0
docs or also to the 3.2 docs.

In that situation, it seems more likely that they would simply ignore
(or not even think of) the 3.2 docs. Out of sight, out of mind. But
then the value proposition of having two sets of docs really just
comes down to saying, "It's hard for contributors to ignore a section
called 'Qubes 3.2' when they're on 4.0. Let's make it easy for them by
moving that to a different doc." That seems kind of uncharitable to
our contributors.

We'd also tend to lose out on contributions that apply to both 3.2 and
4.0. Suppose someone *is* familiar with both versions and adds some
valuable content that's true of both versions. If they, too, forget
that the 3.2 docs exist, that's a loss.

> Tom Zander makes some good points, too.
>
> OTOH, I don't want to belabor the issue -- and I'm far from
> certain anyway, this is about psychology.
>

Neither do I. I just want to make sure that we think things through,
and that the costs are really worth the benefits, before jumping into
a new system.

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAlpYPLQACgkQ203TvDlQ
MDChARAAr+BQwC2lvsjaTERhAwOx0DpuPy3JDhEzUDuQ0pT2dvXp7Lq8bk7DXhA/
5QQyyKO2NyNLuPOFCrBvel719iFzIN378w42gbDHFx8z0Torg+XN6YbuCQhQ/zGs
yZG6zHj87HJOD6z3l82nH/FtZQrtg8iCeHrLomW9DYNso0bO6RLvyxZDR0uk3Q58
++/D0OEDozbTWlsuFR/Yef9cWQbsh9BGreRmF6qkgdrYzzAygUJaFYMdKdIgvByN
P4JZQq4GWp2GjetpFMw2Nc2v1u6aE7u6XHcdykOD2QF9oggx35eBuYWgvnD5hJd3
HZ/xSbY5LtFxny7FoMQgFcrwtbHbOL6RuaK7N2rXzl8G1sXkxgF9gLaFe12zGD1O
QKofza5UqjQxYMvXC74hL2+eCJGnwyfnEpX+91uw36ku/54P1vbzAfcVxfDbDX79
gF2jC+adSN8E/SC1+nhmkff8SLsuyHwPJxPyZrth9RXPm9CyVNaR7v38WEnjnYAM
AWatWYWX1J+nGp939A+OoeOR0sO7lFNq/3QYfCRAtaCRIkrOYH+hKvdEUlVJNj+U
quKiO6UZ/ObzSLyhYbpz1rCmdQWhpVcM4Pr7s5DYHcR3v+VDrPV8TjIqbJthkZWF
t29NZsu/AZ18UuvSG1wC1DcRfM5DbUXaEOoVmzG10k+QZbCinXw=
=LcZz
-----END PGP SIGNATURE-----

[awokd]

On Fri, January 12, 2018 4:20 am, Andrew David Wong wrote:

> It shouldn't require much effort. In most cases, all you have to add
> is `## Qubes 3.2` above the existing documentation, shift the rest of the
> headers down one by adding a `#` in front of each one, then add `## Qubes
> 4.0` above the 4.0 content you want to add. It might be
> slightly trickier if the current headings use the underlining syntax. This
> requires basic familiarity with Markdown, but that's already required for
> most doc contributions. Only one person has to do this for each document,
> and many documents will not even require this because the content applies
> to both 3.2 and 4.0.

Would it be of value if I went through the published Docs and added these
version headers? Should newer versions be added at the top (so 4.0 before
3.2 content)? 4.0 might just be "TBD".

[Tom Zander]

On Friday, 12 January 2018 11:18:19 GMT 'awokd' via qubes-users wrote:
> Would it be of value if I went through the published Docs and added these
> version headers? Should newer versions be added at the top (so 4.0 before
> 3.2 content)? 4.0 might just be "TBD".

I think that would be wonderful,

my main issue is with the not knowing if the current docs are actually
applicable still.
If someone could do as much as flag known out of date content as 3.2 only,
this would be a huge help.

The problem of knowing / identifying what isn't actually applicable anymore
is the main one that I think is causing pain right now.

Thanks!

[Holger Levsen]

On Fri, Jan 12, 2018 at 01:04:23PM +0000, 'Tom Zander' via qubes-users wrote:
> On Friday, 12 January 2018 11:18:19 GMT 'awokd' via qubes-users wrote:
> > Would it be of value if I went through the published Docs and added these
> > version headers? Should newer versions be added at the top (so 4.0 before
> > 3.2 content)? 4.0 might just be "TBD".
> I think that would be wonderful,

I'm not so sure, why not use git branches?


--
cheers,
Holger

[Tom Zander]

On Friday, 12 January 2018 13:09:35 GMT Holger Levsen wrote:
> I'm not so sure, why not use git branches?

That has my preference still, but I'm ok for any workable solution.

[awokd]

On Fri, January 12, 2018 1:04 pm, Tom Zander wrote:
> On Friday, 12 January 2018 11:18:19 GMT 'awokd' via qubes-users wrote:
>
>> Would it be of value if I went through the published Docs and added
>> these version headers? Should newer versions be added at the top (so 4.0
>> before 3.2 content)? 4.0 might just be "TBD".
>>
>
> I think that would be wonderful,
>
>
> my main issue is with the not knowing if the current docs are actually
> applicable still. If someone could do as much as flag known out of date
> content as 3.2 only, this would be a huge help.
>
> The problem of knowing / identifying what isn't actually applicable
> anymore is the main one that I think is causing pain right now.

I have a relatively good amount of experience so should be able to call
out which is which on sight. If not, I can I point that out too in the 4.0
TBD section.

To your point, some of these docs are pretty version specific.
https://www.qubes-os.org/doc/qubes-r3-building/ as a possibly bad example.
It's similar to the 4.0 build procedure but at least the name should be
generalized then. I think I agree with you those should be separated. I'll
plan on skipping them for now.

I'm a bit concerned it's going to result in ugly looking documents too,
but at least by splitting out the contents now it will be easier in the
future to move into separate documents if we go that route.

[awokd]

On Fri, January 12, 2018 1:09 pm, Holger Levsen wrote:

> I'm not so sure, why not use git branches?

It doesn't sound like that's the route the Qubes team wants to take right
now, but at least splitting the content on the same page would make it
easier to migrate to that approach if they change their minds!

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On 2018-01-12 08:00, 'awokd' via qubes-users wrote:
> On Fri, January 12, 2018 1:09 pm, Holger Levsen wrote:
>
>> I'm not so sure, why not use git branches?
>

One reason that comes to mind:

Segregating the documentation into two different branches would mean
that contributions that apply to both Qubes versions would only end up
in one branch, unless someone remembers to manually submit the same
thing to the other branch and actually makes the effort to do so. Most
of the time, this won't happen. When it does, it means a second pull
request that has to be reviewed. Over time, the different branches
will diverge in non-version-specific content. Good general content
that was submitted only to the 3.2 branch will effectively disappear
once 3.2 is deprecated. (Even if it's still on the website, no one
will look at it, since it'll explicitly be in the subdirectory of a
deprecated version. And there will be a motivation to remove it from
the website so that search results aren't populated with out-of-date
information.)

> It doesn't sound like that's the route the Qubes team wants to
> take right now,

Not necessarily. We want to take whichever route is best. We just want
to be sure it would be a big enough improvement to be worth the
associated costs. As I wrote above:

"If there turn out to be significant, compelling reasons to make
completely separate sets of docs (one for 3.2 and one for 4.x), of
course I'd be happy to do that. We should weigh the costs and
benefits, and choose whichever system is best. From a maintainability
perspective, it seems simpler and easier just to have a single set of
docs, and that's what Qubes has always had, so that's why it's the
default system right now. That's not set in stone, but I think an
alternative system should deliver significant benefits for it
be worthwhile for us to move from the default system. So far, it seems
like the objections to sticking with the default system and simply
having separate sections within the existing docs rest on
misunderstandings about how that system would work, but I'd be
happy to be convinced otherwise. :)"

> but at least splitting the content on the same page would make it
> easier to migrate to that approach if they change their minds!
>

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAlpZcEkACgkQ203TvDlQ
MDCcZBAAnmAlCRfKluzVBd36jqGoXGsk9efWDJSSSIS2OUsebk6Tv+cwvDcOfzA6
HhevMmP6iMB637NkHfDe/aMLbmLfq+401g1Ob5JLzvZ008K3Cb88da0VTUmtQ/k1
DKAusV0j/eNGNg9UM9hpRu2XLHdt7fAovIllARKc2hoDLeNA5uxzb0y2ByArpNib
UpaNRZPTPAOCMl2RqjWQIBVhez0Ve8chTqrEx6RHF1NoIBD2FZxJw331z7YLwNUL
iLBtpD928mywhk3VeOZtipP4W6W5l3cgxprYGzU/unxKltOb4D1T5iD+dzkBftFr
euGg07OY5w/lqr9FBONqtgtKLWNrOsT1Ko60eCOuXLA2oBGcV4wIB2Zb22J0JPgW
rCqTn2vhF4wLLW/h0hhMdmj9abxQoShrLoLiUfJa8i+R8yyxWImiY6VbCP7gjAF+
kMHmA88i3yroQawJBwmfnfgGtEpBcFo3+L2uYSUnIQGt3BIW7HYNV1EHKvlA/PIN
xUZGAQkPeaCni3GhsVcGBg3YQcYyrcEn5KyRXQYwvHDUBfA5LDmXH26HCDA6el0F
MOoZk408Mg0QUZD/Tk72K50c5/XzNC9TF7f9JLWtZ+i2ClJu62OORMpYx4ncaq+e
sg6rrSrTZkeZejXh0XbraHNs8WiZVt50kV0JGAFhzSHExnp3Xio=
=WcO8
-----END PGP SIGNATURE-----

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On 2018-01-12 07:58, awokd wrote:
> On Fri, January 12, 2018 1:04 pm, Tom Zander wrote:
>> On Friday, 12 January 2018 11:18:19 GMT 'awokd' via qubes-users
>> wrote:
>>
>>> Would it be of value if I went through the published Docs and
>>> added these version headers? Should newer versions be added at
>>> the top (so 4.0 before 3.2 content)? 4.0 might just be "TBD".
>>>
>>
>> I think that would be wonderful,
>>
>>
>> my main issue is with the not knowing if the current docs are
>> actually applicable still. If someone could do as much as flag
>> known out of date content as 3.2 only, this would be a huge
>> help.
>>
>> The problem of knowing / identifying what isn't actually
>> applicable anymore is the main one that I think is causing pain
>> right now.
>
> I have a relatively good amount of experience so should be able to
> call out which is which on sight. If not, I can I point that out
> too in the 4.0 TBD section.
>

That would be very helpful! Thank you!

> To your point, some of these docs are pretty version specific.
> https://www.qubes-os.org/doc/qubes-r3-building/ as a possibly bad
> example. It's similar to the 4.0 build procedure but at least the
> name should be generalized then. I think I agree with you those
> should be separated. I'll plan on skipping them for now.
>
> I'm a bit concerned it's going to result in ugly looking documents
> too, but at least by splitting out the contents now it will be
> easier in the future to move into separate documents if we go that
> route.
>

Doing this will provide evidence that helps us decide which system to
us. For example, if it turns out that nearly every document has to be
split into two sections, that might be a strong indication that there
should just be two sets of documents. But if it's only 30%, or if it's
usually just certain sections *within* documents, for example, then it
might make more sense to stick with the current system.

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAlpZcjIACgkQ203TvDlQ
MDBB8hAAhuP4K0RtpYbTQoDRSKjomgx7q3TWZUziYNJ7TE2MCgDiGCqs7Bdh8Pk7
4PgNlkOOTVUEgq4ehOgCXbTEL/Gofaat2vrxdPDcXl94Gd4Oi9dhN6c2SGBEAhkL
nkyjY6iXxTRBd0+duqI4jN5CIAUcxOPqV+D/naQaLS2uiRX73rwJkAYDHOhiRUY1
hjd+iLK1AzGjjqJs7yBn2UshxwIMZnEHn7GnwzbI1at+vFOIXLaMk5xIEUiekICL
+9NeC4ijbOVYIni6UjiJ4Dtr1sGk0Nm8XNHKve5/YOlQEDcciXDFk158yZmYUcR+
h9XwV4afPpSe17p+SZiZLG4UkYjner1GSPY5GhbqHM5+FpYEeWmCbkiSBI9HAEiZ
6PMSUwY2yLJ9V7jQHhzbCqYeLDKcsssn/VmNrcH8aPjrs8dDAxmSYHt+Q0O3mn5G
Ka4zgCt6t91PUxYIE2HqAQB3mOSLtKd8gp3rmgkR/HcawSxQfy8Oh6atYMnTu2fG
5G3g407cwwXWedSO9CrqkNz9anCt2MjVKnTXy5j0q0OQtkC7n8GwOz7Q8nPAnH27
WGUlp+0dG6PlLn/MqiR66JdxFMmfv37ATwXj03Zol0JY51B3kczeXzsB5ky6zi2T
T9YjFN0oiJFA3fxCt4iMc51vSB56ufYG5yROCnhbdsfksYU59sQ=
=EGor
-----END PGP SIGNATURE-----

[awokd]

Resuming working my way through splitting up the documentation now that
the 3.2 vs. 3.3 question has been mostly settled. Some general questions:

1. Should I open an issue for tracking and move the discussion over there?
Move to qubes-devel? Keep here?
2. The command line tools in particular
(https://www.qubes-os.org/doc/vm-tools/ and
https://www.qubes-os.org/doc/dom0-tools/) seem Wrong to try to share the
same pages for 3.2 and 4.0. Not only is the selection of commands slightly
different between versions, but many have slightly different options ("-a"
vs. "a"). I'm thinking of copying all the existing pages, appending "4" so
they can be linked to directly, and putting in their own section.
Thoughts?
3. Some of these documents are pretty outdated. Should we have an Archive
link and move stuff like
https://www.qubes-os.org/doc/template/fedora/upgrade-18-to-20/ to it so it
doesn't clutter up the main Docs page?

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On 2018-01-25 12:28, awokd wrote:
> Resuming working my way through splitting up the documentation now
> that the 3.2 vs. 3.3 question has been mostly settled. Some
> general questions:
>
> 1. Should I open an issue for tracking and move the discussion
> over there? Move to qubes-devel? Keep here?

Please open an issue in qubes-issues.

(Doing so does not preclude discussion here or on qubes-devel.)

> 2. The command line tools in particular
> (https://www.qubes-os.org/doc/vm-tools/ and
> https://www.qubes-os.org/doc/dom0-tools/) seem Wrong to try to
> share the same pages for 3.2 and 4.0. Not only is the selection of
> commands slightly different between versions, but many have
> slightly different options ("-a" vs. "a"). I'm thinking of copying
> all the existing pages, appending "4" so they can be linked to
> directly, and putting in their own section. Thoughts?

Those pages are automatically generated from the man pages stored with
the tools' source code in their own respective repos, so any changes
to those pages in qubes-doc will be overwritten. Changes should be
made to the original files instead. That way, the changes will persist
when the qubes-doc versions are automatically generated.

I agree that the tool man pages should not be shared between 3.2 and
4.0 (but they probably wouldn't be anyway, due to the nature of the
system just described).

> 3. Some of these documents are pretty outdated. Should we have an
> Archive link and move stuff like
> https://www.qubes-os.org/doc/template/fedora/upgrade-18-to-20/ to
> it so it doesn't clutter up the main Docs page?
>

There are two categories of outdated documents:

1. Documents that we want updated (but that no one has updated yet).
2. Documents that are about old topics (but are otherwise good).

I don't think it would make sense to move documents of category 1 into
an archive section, since that would incorrectly suggest that we don't
want or expect them to be updated.

The old Fedora upgrade documents fall into category 2. However, it
looks like they (and perhaps the release notes for unsupported Qubes
versions) are the only major offenders visible in the main table of
contents. This is understandable, since a new version of the document
gets added each time there's a new version of the corresponding
software. I think it makes sense to handle these cases specifically,
by creating a page that collects all the versions of each one. I'll do
this now.

In general, it's worth thinking about whether we even want to keep
severely outdated category 2 documentation around. Does it have any
value anymore, or will it just produce misleading search results?
(Note that it will all remain permanently archived in the git revision
history, so it's mainly a question of visibility on the website.)

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAlpqojUACgkQ203TvDlQ
MDDG4Q//Q6ND5fzToFv6KKQn4SzkcUSIIZQKtMPTlG9BkC7UCgjFZ+7sxrLA1N5X
H+9Z88+QNRL6FBOa6DHpFZOOA6vomzw0HXkTF+g9VcplsJIFZh6iB7lpSta1XwKU
1DG+ayF0oDd8PxKtSjaslMWRsr9p9cApPM7G+z6sGLB34LLZfolx19FRhwcpfBBK
09wyaAzmr5sF9oO8rSxC1llz5u75GatXUu+tHIc3Jh9C4hBtX7MSwyoq7eTkXnKQ
VpS35O8thmhm6cEuyNQsUD7ia853lWRcdTur1Am7GIx3jwl7VBQ6YCqanLRLueaI
tm4LbBfNrZcxFexHp0mB+veDeIfkC4cJZm8/sbjrHEicK6Cuvp5E0E6iLOaMw9gI
y3D1ypbEwMXyYQFPWW0h488pNow9RCrTHTcvBhgyIBw0xhCe0j89RZpbV3UB79k1
n5YRoj36XXRmHho/KVIlFMrzsXE6q9sawU8P1/Q7mBjX3fQLDoOEwFMtHRZTiFLk
NOkqv328xsqJy1smKgfFI4cpNMa1+Be0zGjqRWjBFNTqWEoNPkAbDbhbiwYPZYop
CW0lDS6b6dc2KCMcxlP+3BwuFC+pS9Yw/Qw2B0yceVjrH0YnLoVkOaqC6ojGx6DH
JAFtJLB6FbXssbK3JASOvGKpMxcktfQe3quJZmTaMY2yLkBaomA=
=8MfO
-----END PGP SIGNATURE-----

[Alex Dubois]

Happy to contribute. maybe we can have a direct conversation so that we can discuss what is needed and where I feel comfortable...

[awokd]

On Fri, January 26, 2018 3:36 am, Andrew David Wong wrote:
> On 2018-01-25 12:28, awokd wrote:
>> 1. Should I open an issue for tracking and move the discussion
>> over there? Move to qubes-devel? Keep here?
>
> Please open an issue in qubes-issues.

https://github.com/QubesOS/qubes-issues/issues/3495

> I agree that the tool man pages should not be shared between 3.2 and
> 4.0 (but they probably wouldn't be anyway, due to the nature of the
> system just described).

What will be the naming convention for direct links? I can see sometimes
we'd want to link to the latest version of qvm-whatever, and other times
when we want to link to a specific major version.

> I
> think it makes sense to handle these cases specifically, by creating a
> page that collects all the versions of each one. I'll do this now.

Thank you.

> In general, it's worth thinking about whether we even want to keep
> severely outdated category 2 documentation around. Does it have any value
> anymore, or will it just produce misleading search results? (Note that it
> will all remain permanently archived in the git revision history, so it's
> mainly a question of visibility on the website.)

My vote is to axe it.

[awokd]

Speaking only on my own behalf of course, thank you. Editing the docs is
pretty straight-forward (https://www.qubes-os.org/doc/doc-guidelines/), so
I'd suggest jumping in and editing whatever you are comfortable with. I'm
coming across documents where someone else has already gone in and called
out or updated with R4.0 content, so thanks to those contributors as well!

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

I agree.

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAlpr1q4ACgkQ203TvDlQ
MDAmmw//f5oa73EABlkL+6g78pOalsHZaX9jYbcwvfpZAycrdpYaxiXxxeIAjY/+
p5PZQe/0b5CQf1N3g7jcDcN7HzqztZgtpMmOPyWrZ1VMMBfJ2d8TmjAC9OU/d0Pv
Jf7KujBhD+hJVRh2Zel8xIis89+5tdM2IKWJsetAuZgTssmvGVAXy+NzEXzchBbh
jszjL5RixsxhSeBVkvNCuBSiD3XGGYBp3beOj8zvvnLu5mTVJA7p2hI3MAtADqlU
yiWIpoTz1FBLfbo33ETl9O9NTP9v9pzs3175Llprf93XWABV9qZEY+QoAPZdEAac
C/T0Fm9UZFJ/2xaNQiNBHqzO7CSOVUqOpwJQoiQBleeorIvCSpfeJdCEqUQ7PGKS
rnAq9Sm8Fr7BiDfXQU99MJQbqmMeJVtq6BeUUx/JlcS7gW7KUzZ3W9LfirMdHRdQ
KAuaG/pqio1LBtZatbXBUvCnQ8uWctaPJ4YknqPc99rvgCFl3if3dFxQRBcr56RH
nXcPUifk+jbgFQzEjiyCzANYS9OdmXBsYa0QPWN/ZdIw4Dvl23J6qqcY5Vs7pEyJ
EEm/sLiinPrQo9h5WjH7+55PQRcnPqm71rwC8fMlblde2Nx89fMgbksB0BQIyX+x
pTxjh2feeWpDtf/bL1zfJ+zNAR2mEyxJML0Dbc6+Kj+EBTwGUtU=
=czGG
-----END PGP SIGNATURE-----

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On 2018-01-26 05:14, awokd wrote:
> On Fri, January 26, 2018 3:36 am, Andrew David Wong wrote:
>> On 2018-01-25 12:28, awokd wrote:
>>> 1. Should I open an issue for tracking and move the discussion
>>> over there? Move to qubes-devel? Keep here?
>>
>> Please open an issue in qubes-issues.
>
> https://github.com/QubesOS/qubes-issues/issues/3495
>
>
>> I agree that the tool man pages should not be shared between 3.2
>> and 4.0 (but they probably wouldn't be anyway, due to the nature
>> of the system just described).
>
> What will be the naming convention for direct links? I can see
> sometimes we'd want to link to the latest version of qvm-whatever,
> and other times when we want to link to a specific major version.
>

We could either have different subdirectories for each version or
include the version in the page name, as we do for some other
version-specific pages.

>> I think it makes sense to handle these cases specifically, by
>> creating a page that collects all the versions of each one. I'll
>> do this now.
>
> Thank you.
>
>> In general, it's worth thinking about whether we even want to
>> keep severely outdated category 2 documentation around. Does it
>> have any value anymore, or will it just produce misleading search
>> results? (Note that it will all remain permanently archived in
>> the git revision history, so it's mainly a question of visibility
>> on the website.)
>
> My vote is to axe it.
>

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAlpsEAwACgkQ203TvDlQ
MDAhCg//Xxt+qfhlLYXYoudWzpGX9WSwwBQHZpH/A6j0zZEhgIYl/sPtF66Mmxwx
QOWA7DEElbojIRQ+DmVvt8FB4RWJkxRw9mqUY8aMbh5qVXHMbjiBDLfWDsnwjRnJ
ZJREO450qYHDesg/g+8DasFbXE7D1qBxuUBM+uRvTaqzj9fhUUtCvI0NAUBZcv/u
6+0IFSTbm6fw4XyhfVYJEXpjuBI2WCfA++6mFlnAx0UY6AQenlnxRtOgEdK+N8wb
403fX7e0CaJhzCnXd+4g5i9Dm2ogewNAwHK/TLPXathJzmYmruZgzIJgiSrcUwVB
vHrsPi3ZqPgR6vZkW/DwMBBjz0s+Y/WudBpDhFeXDJ/JbOU5mW1E/63LpCyB8p0+
V9Y+4pAkbdWuzX8JojNGSJ6K0ZrsGRgb3QIyhi8yRCwgNqUqjW6y/VitmeAi3HGT
KPSaM8b8MjnEtfI6KQUNPOqS8lO9cX5D5tsPu64FGXx7ZTieVdCOl8oDjWduc4hU
1W2FxzH1p+hr6X17qYsUbwbyyr2lqV1so8g5ASitOflcMNqPHN4rfXRI9dKu5gfL
8PmpDk2hQUeaLy1RbpBrUzbHp1JnqmwMg1bfm9BJrqDbyOqXJapVLAuoAvg/bQmZ
QfzRQPrZpjpS/6VW+qTojRj0zGadqE7NBiBvBIQF+0Z5bZ/Bck8=
=U+U5
-----END PGP SIGNATURE-----

[Tom Zander]

On Thursday, 25 January 2018 19:28:58 CET 'awokd' via qubes-users wrote:
> Resuming working my way through splitting up the documentation now that
> the 3.2 vs. 3.3 question has been mostly settled. Some general questions:

Awesome!

I was thinking about the qubes docs when I saw a wiki that had a banner for
articles (or sections) that were known to be "disputed".

I was wondering if it might be useful to have such a concept on the doc
pages, it may invite people to actually add their knowledge.

[Marek Marczykowski-Górecki]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On Fri, Jan 26, 2018 at 11:37:31PM -0600, Andrew David Wong wrote:
> On 2018-01-26 05:14, awokd wrote:
> > On Fri, January 26, 2018 3:36 am, Andrew David Wong wrote:
> >> On 2018-01-25 12:28, awokd wrote:
> >>> 1. Should I open an issue for tracking and move the discussion
> >>> over there? Move to qubes-devel? Keep here?
> >>
> >> Please open an issue in qubes-issues.
> >
> > https://github.com/QubesOS/qubes-issues/issues/3495
> >
> >
> >> I agree that the tool man pages should not be shared between 3.2
> >> and 4.0 (but they probably wouldn't be anyway, due to the nature
> >> of the system just described).
> >
> > What will be the naming convention for direct links? I can see
> > sometimes we'd want to link to the latest version of qvm-whatever,
> > and other times when we want to link to a specific major version.
> >
>
> We could either have different subdirectories for each version or
> include the version in the page name, as we do for some other
> version-specific pages.

I'd go with different subdirectories - it will be easier to handle (both
generate and later reference).

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
-----BEGIN PGP SIGNATURE-----

iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAlps18QACgkQ24/THMrX
1yyZ8Af+P6P0CjFiUiW1HdMHe5NCje/ZxjJxpSE+HXLPT/2Hr+Bhm/CjIGXS7cOr
/IO920qG3+c6EmDxBplIDCCaov5xz3jxWih5JjtRR9FUx29yCGwm9Fu2vHPiiaDJ
RvEmTFRfkGgsm3EOJ1U/j7uao7uuMPrpRmyVNyWWIKHKPk6S/DmBodVQepl7uE2Q
Mw/uXITtl3EaBfGoN/W6lnCNc0/0E6wPLUv6rsMaeSEAcihzRlrzAXDDdcNYWMQL
EWEYV/mqdXjtksqtzLMCpQwiCkuGBOhIptQjRZ3DqBPQZQm5eQH4+tbytBR63nby
tQqOXmUDWjBFdj3UuulZkQVbRUxNuw==
=6lu1
-----END PGP SIGNATURE-----

[Manuel Amador (Rudd-O)]

This ought to be the chosen solution.  Mount the release 4.0 branch on doc/ and the older releases on doc/<release>, then provide links at the top (Doc for <unreleased / <4.0> / <3.2>).

-- 
    Rudd-O
    http://rudd-o.com/

[Manuel Amador (Rudd-O)]

On 13/01/2018 03.34, Andrew David Wong wrote:

On 2018-01-12 08:00, 'awokd' via qubes-users wrote:
> On Fri, January 12, 2018 1:09 pm, Holger Levsen wrote:

>> I'm not so sure, why not use git branches?


One reason that comes to mind:

Segregating the documentation into two different branches would mean
that contributions that apply to both Qubes versions would only end up
in one branch, unless someone remembers to manually submit the same
thing to the other branch and actually makes the effort to do so. Most
of the time, this won't happen. When it does, it means a second pull
request that has to be reviewed. Over time, the different branches
will diverge in non-version-specific content. Good general content
that was submitted only to the 3.2 branch will effectively disappear
once 3.2 is deprecated. (Even if it's still on the website, no one
will look at it, since it'll explicitly be in the subdirectory of a
deprecated version. And there will be a motivation to remove it from
the website so that search results aren't populated with out-of-date
information.)

That ought to be part of the review process, don't you think?  ("Have you opened PRs for these other branches?")

--

    Rudd-O
    http://rudd-o.com/