Opened 8 years ago

Closed 8 years ago

#1617 enhancement closed fixed (fixed)

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

Reported by: hypatia Owned by:
Priority: highest Milestone:
Component: core Keywords: documentation
Cc: hypatia, jml Branch:
Author: Launchpad Bug:

Description

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

Change History (25)

comment:1 Changed 8 years ago by hypatia

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

comment:2 Changed 8 years ago by hypatia

  • Keywords review added
  • Priority changed from normal to highest

comment:3 Changed 8 years ago by hypatia

  • Owner changed from hypatia to radix

Assigning to radix for review.

comment:4 Changed 8 years ago by hypatia

Branch is docs-notestoself-1617

comment:5 Changed 8 years ago by radix

  • Keywords review removed
  • Owner changed from radix to hypatia

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...

comment:6 Changed 8 years ago by hypatia

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

comment:7 Changed 8 years ago by hypatia

  • Cc hypatia added
  • Keywords review documentation added
  • Owner changed from hypatia to radix

Reassigning for review. Changes:

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

comment:8 Changed 8 years ago by hypatia

  • Owner radix deleted

comment:9 Changed 8 years ago by exarkun

Why is this ticket unowned?

comment:10 Changed 8 years ago by hypatia

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

comment:11 Changed 8 years ago by 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

comment:12 Changed 8 years ago by 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.

comment:13 Changed 8 years ago by 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.

comment:14 Changed 8 years ago by exarkun

Okay I think some stuff has been fixed now.

Someone else needs to review the changes I made.

comment:15 Changed 8 years ago by jml

  • Owner set to jml
  • Status changed from new to assigned

comment:16 Changed 8 years ago by jml

  • Owner changed from jml to jerub
  • Status changed from assigned to new

comment:17 Changed 8 years ago by jerub

  • Cc jml added
  • Keywords review removed
  • Owner changed from jerub to exarkun

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?

comment:18 Changed 8 years ago by exarkun

  • Keywords review added
  • Owner changed from exarkun to jerub

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.

comment:19 Changed 8 years ago by jerub

  • Keywords review removed

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', '']:

comment:20 Changed 8 years ago by jerub

  • Owner changed from jerub to exarkun

comment:21 Changed 8 years ago by exarkun

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

comment:22 Changed 8 years ago by exarkun

  • Keywords review added
  • Owner changed from exarkun to jerub

Are you satisfied with the branch now?

comment:23 Changed 8 years ago by jerub

  • Keywords review removed
  • Owner changed from jerub to exarkun

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

comment:24 Changed 8 years ago by exarkun

  • Resolution set to fixed
  • Status changed from new to closed

(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).

comment:25 Changed 3 years ago by <automation>

  • Owner exarkun deleted
Note: See TracTickets for help on using tickets.