Opened 12 years ago

Closed 11 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, Jonathan Lange Branch:
Author:

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 12 years ago by hypatia

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

comment:2 Changed 12 years ago by hypatia

Keywords: review added
Priority: normalhighest

comment:3 Changed 12 years ago by hypatia

Owner: changed from hypatia to radix

Assigning to radix for review.

comment:4 Changed 12 years ago by hypatia

Branch is docs-notestoself-1617

comment:5 Changed 12 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 11 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 11 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 11 years ago by hypatia

Owner: radix deleted

comment:9 Changed 11 years ago by Jean-Paul Calderone

Why is this ticket unowned?

comment:10 Changed 11 years ago by hypatia

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

comment:11 Changed 11 years ago by Jean-Paul Calderone

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 11 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 11 years ago by Jean-Paul Calderone

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 11 years ago by Jean-Paul Calderone

Okay I think some stuff has been fixed now.

Someone else needs to review the changes I made.

comment:15 Changed 11 years ago by Jonathan Lange

Owner: set to Jonathan Lange
Status: newassigned

comment:16 Changed 11 years ago by Jonathan Lange

Owner: changed from Jonathan Lange to Stephen Thorne
Status: assignednew

comment:17 Changed 11 years ago by Stephen Thorne

Cc: Jonathan Lange added
Keywords: review removed
Owner: changed from Stephen Thorne to Jean-Paul Calderone

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 11 years ago by Jean-Paul Calderone

Keywords: review added
Owner: changed from Jean-Paul Calderone to Stephen Thorne

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 11 years ago by Stephen Thorne

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 11 years ago by Stephen Thorne

Owner: changed from Stephen Thorne to Jean-Paul Calderone

comment:21 Changed 11 years ago by Jean-Paul Calderone

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

comment:22 Changed 11 years ago by Jean-Paul Calderone

Keywords: review added
Owner: changed from Jean-Paul Calderone to Stephen Thorne

Are you satisfied with the branch now?

comment:23 Changed 11 years ago by Stephen Thorne

Keywords: review removed
Owner: changed from Stephen Thorne to Jean-Paul Calderone

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

comment:24 Changed 11 years ago by Jean-Paul Calderone

Resolution: fixed
Status: newclosed

(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 7 years ago by <automation>

Owner: Jean-Paul Calderone deleted
Note: See TracTickets for help on using tickets.