[Twisted-Python] Developer docs should be updated on wiki when steps changed in code?

[Glyph]

> On Feb 3, 2021, at 4:51 AM, Craig Rodrigues <rodrigc at 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 at twistedmatrix.com
> https://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20210203/e1e4ef1e/attachment-0001.htm>