Yes, I think that the discoverability and durability would be part of
some "process". There could be "informal" part, where the design can
take place virtually anywhere and the document can be owned by anyone
(as we do today), then it would be copied to a durable store (asf wiki?)
and a [DISCUSS] thread could be started on ML, followed by [VOTE] (if
needed?) after that, then the document would be marked as accepted and
will be turned into issues. I believe this is how the FLIPs and KIPs are
processed.
Jan
On 5/29/24 17:56, Robert Bradshaw via dev wrote:
While I'm not opposed to having a more formal process for proposals to
go from idea to consensus to implementation, I'm not sure how much
this would solve the primary issues we face (discoverability and
durability). But maybe that could be built into the process? At the
very least we could have an "index" which would give identifiers (and
hopefully good titles) to all the proposals, and maybe have an offline
process to snapshot such docs (even just periodically pulling the
content to a repo like I do with
https://github.com/cython/cython-issues ). I have yet to find a medium
(not even wikis) that facilitates conversation/collaborative editing
to the extent that docs does, but I agree with the downside that
ownership by random individuals can pose a problem.
On Wed, May 29, 2024 at 7:07 AM Jan Lukavský <je...@seznam.cz> wrote:
Hi,
regarding changing the way we document past (and more importantly
future) changes, I've always been a big fan of the FLIP analogy [1]. I
would love if we could make this work for Beam as well, while preserving
the 'informal' part that I believe all of us want to keep. On the other
hand, this could make the design decisions more searchable, transparent
and get more people involved in the process. Having design documents
durable is of course a highly important part of it.
Jan
[1] https://lists.apache.org/thread/whfy3706w2d0q6rdk4kwyrzvhfd4b5kg
On 5/29/24 15:04, Kenneth Knowles wrote:
Hi all,
Yesterday someone asked me about the design doc linked from
https://github.com/apache/beam/issues/18297 because it is now a 404.
There are plenty of reasons a Google Doc might no longer be
accessible. They exist outside the project's control. This is part of
why ASF projects emphasize having discussions on the dev@ list and
often put all their designs directly onto some ASF-hosted
infrastructure, such as a Wiki (Example:
https://cwiki.apache.org/confluence/display/FLINK/Flink+Improvement+Proposals).
In the early days we had a project-owned shared folder but it fell
into disuse.
In my opinion, Google Docs are still the best place for design docs to
get feedback and be revised, but the lack of durability is a downside
to stay aware of. I've also gotten lots of complaints of lack of
discoverability and lack of systematization of design docs, neither of
which would be addressed by a shared folder.
I don't have a proposal or suggestion. I don't think this is super
urgent, certainly not my personal highest priority, but I thought I'd
just share this as food for thought.
Kenn
