Documenting contributions modules and themes

Neil Drumm — Tue, 06 May 2008 20:08:29 +0000

http://lists.drupal.org/pipermail/development/2008-May/029761.html clearly demonstrates that documenting all of contributions on api.drupal.org would be good.

Add concept of projects every project has its own code and set of branches. This should be clear in both the database and UI.

Programmatically manage branch checkouts managing a lot of CVS checkouts would be tedious.

I researched speaking the CVS protocol to directly query the server. This would be tedious to write and might be hard to debug. Documentation on how to get the relevant documentation is at http://ximbiot.com/cvs/cvshome/cyclic/cvs/dev-res.html. I think it is best to keep checkouts in the filesystem.

Three types of branch management should exist:

Filesystem, same as we do now, parse what is at the specified path.
CVS, programmatically make/update a CVS checkout to the files directory using CVS root, CVS module, path, tag, etc. See http://cvs.drupal.org/viewvc.py/drupal/contributions/modules/project/rel... for an example of Drupal code doing this.
SVN, lots of people use it for internal projects, API module should support it.

Programmatically create branch checkouts use update status XML, for example http://updates.drupal.org/release-history/api/5.x, to find and create project branches.

What can be done now:

Update to Drupal 6. All menu changes should happen after this.
Mock-up UI changes for project navigation and other additional UI elements.
Clean up admin screen. It will have to scale a lot more.
Try running API module with modules you use. Pay attention to what works and what is annoying, report your findings here.
Establish standards for hook and @mainpage documentation in contributions.

API module developers

6.x Upgrade Roadmap

ax@drupal.org — Mon, 18 Feb 2008 02:28:35 +0000

There have been various attempts at upgrading api.module to Drupal 6.x. However, it is a complex module, and until now, none of the attempts has yielded satisfying results. We now have the situation that there are 16 patches in the patch queue, none of them thoroughly reviewed, leaving anyone trying to help on this issue without much help and probably causing her to start from scratch again (at least thats what happened to me). Thats why i think we need to break down this issue into smaller tasks. Smaller tasks can more easily be solved, tested, and reviewed. After a subtask is finished, it can be commited to CVS HEAD, giving anyone else a solid starting point for further tasks, without worrying about the base she is working on.

Tasks

api.info. trivial.
api.install. there are 6 patches for this in the queue. to be tested, reviewed, committed.
api.module. the beast. i think this needs at least 2 subtasks:
- general Drupal 6 compatibility. for this i would recommend installing coder.module, checking "Converting 5.x modules to 6.x", and fixing all there errors appearing there. note that even if coder doesn't indicate errors anymore, it probably can still be improved or coded more elegantly.
- api_menu(). i think the way to go for api_menu() is a complete rewrite. it is grown organically and currently exposes 24 menu entries, many of them dynamic. while it would be possible to make it Drupal 6 compatible with some big regular expressions (i did), i think the clean way is to completely overhaul it and use Drupal 6's Dynamic Arguments (Wildcards) and Inheritance rules properly (if i would know how to do this, i would have done it :S).
parser.inc
- mostly "general Drupal 6 compatibility", see above.

Issues and patches for these subtasks should be filed separately with the prefix "Drupal 6: ".

Future work

Windows compatibility. Api.module currently doesn't work on windows because it uses linux path conventions. To enable windows users to help in the upgrade, (part of) my windows compatibilty patch should be committed.
parser.inc should be cleaned up
+clearly separate parsing from database storage
+write unit tests for parsing functions
+maybe use a more lexical syntax analysis (probably using the tokenizer extension) instead of relying completely on regular expressions
+maybe standardize common regular expression components

API module developers