On Mar 1, 2021, at 5:30 AM, Adi Roiban <adi@roiban.ro> wrote:

On Wed, 3 Feb 2021 at 18:09, Glyph <glyph@twistedmatrix.com> wrote:


I can't quickly find the place where we agreed to this, but I think several years ago at this point we had a discussion about moving all these docs into the source tree.  (If they're on the wiki, there's no review process or even a place where updates can be staged for commentary before going live and becoming "official".)

Until this is fully completed, what is the correct thing to do when there is a mismatch between docs on the wiki, and docs in the tree?

Docs in the tree always win.

I still refer to a lot of docs on the wiki, especially for process related things,
so I think it would be nice if the wiki docs were kept up to date, until the day that
they are fully deleted.

Let's start deleting them now, and replacing them with links to the in-tree docs, rather than updating them.  They've been skewing out of date for a long time.  When I was looking for information about how to do a revert, I found wiki docs about linking to revisions in Subversion which didn't mention Github, which gives a flavor for how outdated some of this stuff is.

Thomas, would you mind doing the honors for this document?  Links for process docs should probably be to https://docs.twistedmatrix.com/en/latest/ since, for process information (unlike API information), trunk should be authoritative, not the latest release.

I don't know what wiki page we are talking about here. Any link would help.

Upthread (in the [snip]'d part), Craig referenced https://twistedmatrix.com/trac/wiki/TwistedDevelopment, and I thought we'd migrated some stuff from there.  If not, never mind.

I see this wiki page and it already has a redirection: https://twistedmatrix.com/trac/wiki/ReleaseProcess

My suggestion is that next time a dev needs to update a wiki page, she/he/they should consider moving that page to twisted/twisted repo
narrative docs and create a PR for that change.

Sounds good to me.

I see that Security and Review Process are not yet migrated to narrativedocs.

Does someone want to go file tickets for those?

And I think that "Contributor Advancement Path" can be removed as we now have an informal processes for giving write access to the repo.

Perhaps this proposal has been rejected but I think we should leave a stub in there saying that we could really use some help with a formal process.  The informal process is sort of necessary at the moment, but implicit processes tend to overlook quieter people, and people who are less sure of themselves in the open source social context.  However, improving this process is going to be some work, and we'll have to find someone willing to do it.