Moving stuff out of Misc and over to the devguide

There is a bunch of stuff in Misc that probably belongs in the devguide (under Resources) instead of in svn. Here are the files I think can be moved (in order of how strongly I think they should be moved): PURIFY.README README.coverty README.klocwork README.valgrind Porting developers.txt maintainers.rst SpecialBuilds.txt Now before anyone yells "that is inconvenient", don't forget that all core developers can check out and edit the devguide, and that almost all of the files listed (SpecialBuilds.txt is the exception) are typically edited and viewed on their own. Anyway, if there is a file listed here you don't think should move out of py3k and into the devguide, speak up.

Am 17.01.2011 21:32, schrieb Brett Cannon:
No objections, +1. While it seems convenient to have (e.g.) the list of maintainers directly in the source tree, a) developers already know where to find it, no matter if in Misc/ or devguide/ b) others first have to find it anyway, and it's better to find when embedded in the rest of developer-related docs c) everyone can commit to the devguide as well as to cpython d) people should get used to multiple repos with hg coming Same goes for developers.txt. Georg

On Mon, Jan 17, 2011 at 12:32 PM, Brett Cannon <brett@python.org> wrote:
Wow, that Purify file is really old... Unless anyone can confirm it still works, maybe just toss it? Barry? I would think the best way to decide whether something belongs in the developers guide or in Misc is whether it makes sense for this information to be included in that tar files that people download for specific releases. Especially files that contain stuff that might be useful to copy/paste might still be better off closer to the source code. From that POV the files for which the argument to move them over to devguide is weakest are PURIFY.README (though it really should be named README.purify :-), README.valgrind, and SpecialBuilds.txt. There's also something to be said for keeping version-dependent info closer to the source code -- personally, I would expect to be reading the devguide online. -- --Guido van Rossum (python.org/~guido)

On Mon, 17 Jan 2011 12:32:20 -0800 Brett Cannon <brett@python.org> wrote:
Well it *is* inconvenient in the case of maintainers.rst, which is often consulted casually for daily bug tracker work. Grepping Misc/maintainers.rst is much easier than first having to find again where your checkout of the devguide is, and ensuring it is up-to-date. Also, I see no need to put the maintainers list in the dev guide, actually. Regards Antoine.

On Tue, Jan 18, 2011 at 6:54 AM, Antoine Pitrou <solipsis@pitrou.net> wrote:
Every time I see someone syncing the version-independent maintainers list across branches a little alarm bell goes off in my head to say that file should be somewhere other than the main source tree. It's also quite possible that once the maintainer list is part of the dev guide, triagers will start using the official copy on python.org and the search function in their web browser rather than running grep over a source checkout. So moving the version-independent stuff certainly makes sense, but the stuff that is dependent on a particular version's build system is more questionable. What may make sense is for the devguide to describe the general contents of the files in Misc, but point out that for any given version, the version specific details in Misc take precedence. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia

On Mon, Jan 17, 2011 at 14:41, Nick Coghlan <ncoghlan@gmail.com> wrote:
Ditto for me.
I am not describing what is in Misc. It comes down to a question of whether any core dev-specific stuff should be in Misc that is not a configuration file or not. I say no, that the directory should contain stuff that applies to everyone and not specifically to core devs. -Brett -Brett

On Tue, Jan 18, 2011 at 10:17 AM, Brett Cannon <brett@python.org> wrote:
In that case, I think the memory profiling and debugging info should stay there, as should the build info. Not only can that stuff change between version, but it can all be useful to people that are merely embedding Python or invoking other code from it, and need to dig deeply into what is going on to figure things out. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia

Le 17/01/2011 23:41, Nick Coghlan a écrit :
+1 to moving maintainers.rst to the devguide, a wiki page (I’m volunteering to monitor that page for vandalism), or make it somehow part of the bug tracker. Let’s also take the opportunity to rename it to “experts”, following R. David Murray: “Any module without a listed maintainer is maintained by the community as a whole [...] I think perhaps the name chosen for the file was unfortunate. I view it more as the 'experts' file, rather than the maintainers file, though in some cases the expert is indeed the principle maintainer of the module (such as Vinay for logging).” Bonus question: if we remove maintainers.rst from py3k, what do we do in 3.1 and 2.7? I’d favor removing them over keeping outdated versions. Regards

OK, here is my plan that I will implement: MOVE ---------- developers.txt maintainers.rst README.gdb README.coverity README.Emacs DELETE (seem way too old to still be relevant; tell me if I am wrong) ----------- README.OpenBSD README.AIX cheatsheet LEAVE everything else (with README properly edited and simplified to only list files with non-obvious names) On Mon, Jan 17, 2011 at 12:32, Brett Cannon <brett@python.org> wrote:

On Wed, Jan 19, 2011 at 15:49, Antoine Pitrou <solipsis@pitrou.net> wrote:
That's true of README.Emacs as well. But I'm willing to bet more people will find out about the gdb and Emacs details if we put them online through search engines, blogs, and reading the devguide than anyone ever did by digging through the Misc directory.

Brett, I'm sure I just missed it, but where is the devguide in the Subversion tree? Thx, Skip

Am 17.01.2011 21:32, schrieb Brett Cannon:
No objections, +1. While it seems convenient to have (e.g.) the list of maintainers directly in the source tree, a) developers already know where to find it, no matter if in Misc/ or devguide/ b) others first have to find it anyway, and it's better to find when embedded in the rest of developer-related docs c) everyone can commit to the devguide as well as to cpython d) people should get used to multiple repos with hg coming Same goes for developers.txt. Georg

On Mon, Jan 17, 2011 at 12:32 PM, Brett Cannon <brett@python.org> wrote:
Wow, that Purify file is really old... Unless anyone can confirm it still works, maybe just toss it? Barry? I would think the best way to decide whether something belongs in the developers guide or in Misc is whether it makes sense for this information to be included in that tar files that people download for specific releases. Especially files that contain stuff that might be useful to copy/paste might still be better off closer to the source code. From that POV the files for which the argument to move them over to devguide is weakest are PURIFY.README (though it really should be named README.purify :-), README.valgrind, and SpecialBuilds.txt. There's also something to be said for keeping version-dependent info closer to the source code -- personally, I would expect to be reading the devguide online. -- --Guido van Rossum (python.org/~guido)

On Mon, 17 Jan 2011 12:32:20 -0800 Brett Cannon <brett@python.org> wrote:
Well it *is* inconvenient in the case of maintainers.rst, which is often consulted casually for daily bug tracker work. Grepping Misc/maintainers.rst is much easier than first having to find again where your checkout of the devguide is, and ensuring it is up-to-date. Also, I see no need to put the maintainers list in the dev guide, actually. Regards Antoine.

On Tue, Jan 18, 2011 at 6:54 AM, Antoine Pitrou <solipsis@pitrou.net> wrote:
Every time I see someone syncing the version-independent maintainers list across branches a little alarm bell goes off in my head to say that file should be somewhere other than the main source tree. It's also quite possible that once the maintainer list is part of the dev guide, triagers will start using the official copy on python.org and the search function in their web browser rather than running grep over a source checkout. So moving the version-independent stuff certainly makes sense, but the stuff that is dependent on a particular version's build system is more questionable. What may make sense is for the devguide to describe the general contents of the files in Misc, but point out that for any given version, the version specific details in Misc take precedence. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia

On Mon, Jan 17, 2011 at 14:41, Nick Coghlan <ncoghlan@gmail.com> wrote:
Ditto for me.
I am not describing what is in Misc. It comes down to a question of whether any core dev-specific stuff should be in Misc that is not a configuration file or not. I say no, that the directory should contain stuff that applies to everyone and not specifically to core devs. -Brett -Brett

On Tue, Jan 18, 2011 at 10:17 AM, Brett Cannon <brett@python.org> wrote:
In that case, I think the memory profiling and debugging info should stay there, as should the build info. Not only can that stuff change between version, but it can all be useful to people that are merely embedding Python or invoking other code from it, and need to dig deeply into what is going on to figure things out. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia

Le 17/01/2011 23:41, Nick Coghlan a écrit :
+1 to moving maintainers.rst to the devguide, a wiki page (I’m volunteering to monitor that page for vandalism), or make it somehow part of the bug tracker. Let’s also take the opportunity to rename it to “experts”, following R. David Murray: “Any module without a listed maintainer is maintained by the community as a whole [...] I think perhaps the name chosen for the file was unfortunate. I view it more as the 'experts' file, rather than the maintainers file, though in some cases the expert is indeed the principle maintainer of the module (such as Vinay for logging).” Bonus question: if we remove maintainers.rst from py3k, what do we do in 3.1 and 2.7? I’d favor removing them over keeping outdated versions. Regards

OK, here is my plan that I will implement: MOVE ---------- developers.txt maintainers.rst README.gdb README.coverity README.Emacs DELETE (seem way too old to still be relevant; tell me if I am wrong) ----------- README.OpenBSD README.AIX cheatsheet LEAVE everything else (with README properly edited and simplified to only list files with non-obvious names) On Mon, Jan 17, 2011 at 12:32, Brett Cannon <brett@python.org> wrote:

On Wed, Jan 19, 2011 at 15:49, Antoine Pitrou <solipsis@pitrou.net> wrote:
That's true of README.Emacs as well. But I'm willing to bet more people will find out about the gdb and Emacs details if we put them online through search engines, blogs, and reading the devguide than anyone ever did by digging through the Misc directory.

Brett, I'm sure I just missed it, but where is the devguide in the Subversion tree? Thx, Skip
participants (9)
-
Antoine Pitrou
-
Barry Warsaw
-
Brett Cannon
-
Eric Smith
-
Georg Brandl
-
Guido van Rossum
-
Nick Coghlan
-
skip@pobox.com
-
Éric Araujo