Personally, I try to follow commits on
php.cvs, bug reports, Change Log,
user notes on the online manual..
but I still have the feeling of missing
a lot of changes. After a year away from
the project, I have no clue what was
added, when, and whether it was added
to our documentation or not.
With regard to new features, I've kept the NEWS file up to date (as have
most other developers) with these changes and although these entries may
not be enough for a 3rd party to decipher into manual entries, I can
certainly write up the ones with my name by them when the time comes
(see note about PHP6).
But that's just a question of features, there's also the "unicode
semantics quirks". Some functions which act in a perhaps-unexpected
manner when used in unicode-semantics mode. These are going to be more
difficult to track down, but I'll make an effort to catalog and document
the parts I worked on.
I know that you developers are willing
to help a lot with it, but that you cannot
manage to save the spare time needed to
do it the right way.
I admit that my additions, personally, in the past year have been left
off the documentation radar, but that's due (mostly) to the fact that
these additions have been to PHP6 and (as with PHP5) the lead time on
any release is too long to start advertising features in the manual that
don't exist (from the perspective of the end user). Where is the
documentation team at with regards to when they feel PHP6 features
should start appearing in the manual?
That's why I would
like to propose a simple/small/timeless
change in your CVS commit messages: If
you feel that the change need to be
documented, place the @doc keyword at the
end of your message log entry.
I like that idea. It's a nice clear, consistent flag saying "look
here!". I'll use this from now on.
This small @doc tag could slightly
improve/optimize/sanitize our work on the
documentation. By adding some SQL logging
in loginfo.pl, and storing the following:
- date: commit date
- login: CVS account of the developer
- branch: CVS branch
- files: Changed files
- commit: Commit message before @doc
- desc : Optional developer description after @doc
We would be able to have an interface
displaying a dynamic phpdoc TODO, with
some nice features like a search by PHP
version, extension, assignee, keywords..
Sounds sexy...
Additionally, we can imagine adding an
online help feature on the interface, by
setting a �help� flag on some hardly
understandable change, to have login@php.net
notified of our need for enlightenment.
Well, this sounds like it's more suitable for a manual process, but
however you'd like...
-Sara
Personally, I try to follow commits on
php.cvs, bug reports, Change Log,
user notes on the online manual..
but I still have the feeling of missing
a lot of changes. After a year away from
the project, I have no clue what was
added, when, and whether it was added
to our documentation or not.
With regard to new features, I've kept the NEWS file up to date (as
have
most other developers) with these changes and although these
entries may
not be enough for a 3rd party to decipher into manual entries, I can
certainly write up the ones with my name by them when the time comes
(see note about PHP6).But that's just a question of features, there's also the "unicode
semantics quirks". Some functions which act in a perhaps-unexpected
manner when used in unicode-semantics mode. These are going to be
more
difficult to track down, but I'll make an effort to catalog and
document
the parts I worked on.
Many months ago this unicode topic was discussed a bit, and the
following
RFC came into being (and was accepted):
Proposal for documenting Unicode support:
http://doc.php.net/php/rfc/rfc-proposal-show.php?id=6
Mehdi has rejuvenated the "update to the new doc style" effort,
something
that has held the unicode (and recent PHP features in general)
documentation back a bit. That and the scary task of understanding the
unicode stuff, writing words to explain it, and doing so in a way that
confuses few. Choose a guinea pig extension and let's all make it
happen.
And to those wondering at home, the PHP documentation source is in the
middle of a large change. Each function includes clearly defined
structure
now... like roles/sections for unicode information, a ChangeLog, and
plenty more.
I know that you developers are willing
to help a lot with it, but that you cannot
manage to save the spare time needed to
do it the right way.I admit that my additions, personally, in the past year have been left
off the documentation radar, but that's due (mostly) to the fact that
these additions have been to PHP6 and (as with PHP5) the lead time on
any release is too long to start advertising features in the manual
that
don't exist (from the perspective of the end user). Where is the
documentation team at with regards to when they feel PHP6 features
should start appearing in the manual?
The policy is to document as soon as possible, so feel free to
commit! :)
The manual does document some PHP 6 functions and features currently,
but
not many. About every one or two months, a bug report is sent in by
a confused user ("...PHP 6 isn't released yet!") but the "About" section
mentions we document future PHP versions (yesterday it was updated to
reflect PHP 6). And, each function has a ChangeLog now. Granted using
present tense to describe PHP 6 can be confusing... it's just the way it
is. It'll be here soon!
PHP versions documented in this manual:
http://php.net/manual/about.phpversions.php
That's why I would
like to propose a simple/small/timeless
change in your CVS commit messages: If
you feel that the change need to be
documented, place the @doc keyword at the
end of your message log entry.I like that idea. It's a nice clear, consistent flag saying "look
here!". I'll use this from now on.
Cool, this should prove useful.
Regards,
Philip