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

[Glyph]

> On Mar 1, 2021, at 5:30 AM, Adi Roiban  wrote:
> 
> 
> 
> On Wed, 3 Feb 2021 at 18:09, Glyph  > wrote:
> 
> [snip]
> 
> 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.

> From this wiki page https://twistedmatrix.com/trac/wiki/TwistedDevelopment 
> 
> 
> 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.

-g

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
https://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

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

[Adi Roiban]

On Wed, 3 Feb 2021 at 18:09, Glyph  wrote:

>
> [snip]
>
> 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.

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.

>From this wiki page https://twistedmatrix.com/trac/wiki/TwistedDevelopment

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

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

Cheers
-- 
Adi Roiban
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
https://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

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

[Craig Rodrigues]

On Wednesday, February 3, 2021, Glyph  wrote:
>
>
>
> Docs in the tree always win.
>
> 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.
>



Glyph,

Thanks for the clarification.

This seems like a reasonable direction to follow moving forward.

--
Craig
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
https://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [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  wrote:
> 
> In this PR: 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 
> 
> 
> 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 
> 
> 
> 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/ 
 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

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
https://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

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

[Craig Rodrigues]

In this PR: 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

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

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?

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?

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.

--
Craig
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
https://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python