On Feb 3, 2021, at 4:51 AM, Craig Rodrigues rodrigc@crodrigues.org wrote:
In this PR: https://github.com/twisted/twisted/pull/1461 https://github.com/twisted/twisted/pull/1461 some changes were made to the Twisted development process for running the various linters before committing code.
I noticed that the changes in PR 1461 were not reflected in docs on the wiki, specifically here: https://twistedmatrix.com/trac/wiki/TwistedDevelopment https://twistedmatrix.com/trac/wiki/TwistedDevelopment
which mentions tox environments that have been deleted in PR 1461.
I noticed this, when I recently tried to work on a branch from recent trunk, and when I tried to run some of the commands on that wiki page they didn't work, because they were deleted.
In this post-review comment: https://github.com/twisted/twisted/pull/1461#issuecomment-753695414 https://github.com/twisted/twisted/pull/1461#issuecomment-753695414
I asked Thomas if he could modify the wiki to reflect the changes he made in trunk, but this hasn't been done yet.
My impression in the comments in PR 1461 is that Thomas and Adi want to move all this documentation into the source tree, and delete the stuff on the wiki?
Is this the long term plan?
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/ https://docs.twistedmatrix.com/en/latest/ since, for process information (unlike API information), trunk should be authoritative, not the latest release.
-g
-- Craig _______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com https://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python