Move 'notes to self' documentation aimed at developers *only* into a separate workspace.

[hypatia]

Documents such as doc/pb/specifications/schema.xhtml, which is marked as "all preliminary and is more an exercise in semiconscious protocol design" are mixed in amongst documents designed for use by end users rather than purely by the Twisted developers themselves. It's confusing (to me) to have them there, therefore they should be moved.

Files: doc/pb/specifications/schema.xhtml doc/pb/newpb-jobs.txt doc/pb/use-cases.txt ./doc/core/vision/philosophy.xhtml ./doc/core/vision/naming.xhtml ./doc/core/vision/security.xhtml

To be consistent ./doc/core/howto/policy/ should probably move likewise.

Unless advised otherwise, I will make doc/development and, say, doc/development/plans, doc/development/plans/pb and doc/development/policy

[hypatia]

./doc/legal/contributor-agreement.html should move likewise.

[hypatia]

Assigning to radix for review.

[hypatia]

Branch is docs-notestoself-1617

[radix]

Argh, sorry I forgot about this review. Anyway:

• I think admin/process-docs and admin/release-twisted need to be updated.
• Is admin/book.texinfo used? It has a reference to "vision.texinfo", whatever that is...

[hypatia]

Not sure about admin/book.texinfo, see bug #1857. I'm leaving it for now, it's well out of date anyway.

[hypatia]

Reassigning for review. Changes:

• admin/process-docs updated
• admin/release-twisted updated
• moved roadmap.xhtml and release.xhtml into the development/ directory

[exarkun]

Why is this ticket unowned?

[hypatia]

Not certain who is willing to review. Not radix evidently, not in the last month anyway.

[exarkun]

I merged this forward to docs-notestoself-1617-2 and removed the weird stuff from that big commit in the middle. I started to review this but it's too late now. The things left to do:

• make sure book.tex changes result in a good book still
• make sure index changes don't drop any important information
• make sure release script changes are okay
• make sure process docs changes are okay

[hypatia]

Thanks. FYI: I'm not around this week to fix up stuff, so if the review reveals problems and someone else wants to step in (you mad people you) go right ahead.

[exarkun]

release-twisted seems to be okay. process-docs is upset, though. Quite a few links to the moved documents are no longer valid. I'm not yet sure what the best way to fix this is.

[exarkun]

Okay I think some stuff has been fixed now.

Someone else needs to review the changes I made.

[jerub]

I have no idea how to review this. svn diff gives me nothing useful, and I really have no idea what's actually changed. How do I test this, and how do I examine the actual operations that have been performed?

[exarkun]

You might want to look at `svn log --verbose --stop-on-copy /path/to/branch' to see the individual changes which have been made.

Most of these changes affect the output of admin/process-docs and admin/release-twisted

It may be reasonable to request a list of changes or documentation regarding motivation for specific changes in order to guide the review process, since many of the changes in this branch are renames or other similar operations.

[jerub]

Okay, I've gone through most of the changes, but it's still a little frustrating doing the diffs on moved files. Without reading through everything, I'm willing to take it on faith that the documentation has been updated adequately.

twisted.vfs has been removed from the release by this branch. Why is that?

Commit Message: "get rid of references to no-longer-existent directories from admin tools"

--- admin/release-twisted       (revision 17737)
+++ admin/release-twisted       (revision 17738)
@@ -22,6 +22,7 @@
 
 packaged_projects = dist.twisted_subprojects[:]
 packaged_projects.remove('web2')
+packaged_projects.remove('vfs')
 
 
 def makeCommands():
@@ -150,10 +151,10 @@
     ver = dist.getVersion('core')
     os.chdir('Twisted.exp')
 
-    for docdir in ['howto', 'howto/tutorial', 'howto/policy', 'upgrades',
+    for docdir in ['howto', 'howto/tutorial', 'upgrades',
                    'examples',
                    'upgrades/2.0', # ugh
-                   'specifications', 'vision', '']:
+                   'specifications', '']:
         lore(ver, os.path.join('doc/core', docdir))
     # development docs go in core, for lack of anywhere better
     for docdir in ['legal', 'pb', 'policy', '']:

[exarkun]

twisted.vfs was never supposed to be part of a release.

[exarkun]

Are you satisfied with the branch now?

[jerub]

Yeah, I've read through stuff again, and I'd love it if this branch were merged :)

[exarkun]

(In [18031]) Merge docs-notestoself-1617-2

Authors: hypatia, exarkun Reviewer: jerub Fixes #1617

This moves documentation targeted at developers /of/ Twisted to a separate directory away from documentation targeted at developers /with/ Twisted.

Associated changes have been made to the admin tools which care about the location of these files, as well as a couple other minor nearby fixes (eg, Python 2.2 is no longer used, vfs is no longer packaged).