Documenting significant decisions in Ubuntu

[Robie Basak]

Dear list,

I asked[1] that we document our decision about Thunderbird, and this led
to a Discourse post[2] aimed at our community to explain what we decided
and why.

In the TB meeting of 26 January[3], we talked at some length on what
we'd like to do in general, and I took the action to put together a
proposal. Here it is.

# What we'd like to improve

 1. The Ubuntu support community sometimes finds itself in the dark when
some changes start affecting users.

 2. Although logs and mailing list archives exist, there is no clearly
identifible record of decisions that have been made by the Technical
Board.

# Proposal

When we make a significant decision, we document a summary somewhere
public. It should:

 1. Be reasonably self-contained, so that readers don't have to read
through discussions to be able to understand the conclusion.

 2. Be directly linkable.

When it's a TB decision, we will additionally link to it from an index
that we will maintain somewhere.

For other Ubuntu developer teams, I'd like to simply encourage that they
do the same. We will lead by example. I should note that some teams have
already been doing this, and I think communication about things so far
in 2021 has been a great start compared to how we did last year. I'd
like more of the same!

# Out of Scope

We did discuss at length where we might document things, where we'd link
to things from, what process to follow, what to recommend, and so forth.
I expect there will also be a question on what "significant" means in my
proposal above. I suggest that for now we leave all of that open. It'd
be an improvement just to consistently have the above, and we can start
to recommend things by example as good patterns emerge. For the TB, we
can just do what we did with Thunderbird: decide when something is
significant and request documentation on individual occasions as we feel
appropriate.

# Examples

https://discourse.ubuntu.com/t/thunderbird-lts-update/20819

Here we used the form "Decision, Rationale, Known Downsides, Available
Workarounds" which I think works well to address the community should
they wonder what happened and why.

https://discourse.ubuntu.com/t/psa-20-04-2-install-failure-bug-images-soon-to-be-recreated/20846

Not exactly a "decision", but this is exactly the sort of thing I think
is really useful for the community. Thanks Laney!

https://ubuntu.com/blog/private-home-directories-for-ubuntu-21-04

On switching to private home directories by default. Thanks Alex!

[1] https://lists.ubuntu.com/archives/technical-board/2021-January/002531.html
[2] https://discourse.ubuntu.com/t/thunderbird-lts-update/20819
[3] https://new.ubottu.com/meetingology/logs/ubuntu-meeting/2021/ubuntu-meeting.2021-01-26-19.59.html

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/technical-board/attachments/20210211/8c94ac15/attachment.sig>