This commit was generated by cvs2svn to compensate for changes in r4407,

[freeside.git] / rt / lib / RT / StyleGuide.pod

diff --git a/rt/lib/RT/StyleGuide.pod b/rt/lib/RT/StyleGuide.pod
index 95b2e3a..f0d1d15 100644 (file)
--- a/rt/lib/RT/StyleGuide.pod
+++ b/rt/lib/RT/StyleGuide.pod
@@ -239,7 +239,27 @@ leads to cleaner code.
         my $var1 = shift;                       # right
         my $var2 = shift;                       
 
+=head2 Method parameters
 
+If a method takes exactly one mandatory argument, the argument should be
+passed in a straightforward manner:
+
+        my $self = shift;
+        my $id = shift;
+
+In all other cases, the method needs to take named parameters, usually
+using a C<%args> hash to store them:
+
+        my $self = shift;
+        my %args = ( Name => undef,
+                     Description => undef,
+                     @_ );
+
+You may specify defaults to those named parameters instead of using
+C<undef> above, as long as it is documented as such.
+
+It is worth noting that the existing RT codebase had not followed this
+style perfectly; we are trying to fix it without breaking exsiting APIs.
 
 =head2 Tests
 
@@ -804,11 +824,9 @@ It is important not to localize  the names of rights or statuses within RT's cor
 
 This is for new programs, modules, specific APIs, or anything else.
 
-Contact for core team is the slashcode-development mailing list.
-
 =over 4
 
-=item Present idea to core team
+=item Present idea to rt-devel
 
 We may know of a better way to approach the problem, or know of an
 existing way to deal with it, or know someone else is working on it. 
@@ -816,9 +834,9 @@ This is mostly informal, but a fairly complete explanation for the need
 and use of the code should be provided.
 
 
-=item Present complete specs to core team
+=item Present complete specs to rt-devel
 
-The complete proposed API to the core team should be submitted for
+The complete proposed API  should be submitted for
 approval and discussion.  For web and command-line programs, present the
 functionality and interface (op codes, command-lin switches, etc.).
 
@@ -827,13 +845,8 @@ boilerplate and fill it in.  You can make changes later if necessary,
 but fill it in as much as you can.
 
 
-=item Announce any changes to interface
-
-If the way it works or how it is called is going to change, notify the core
-team.
 
-
-=item Prepare for core review
+=item Prepare for code review
 
 When you are done, the code will undergo a code review by a member of
 the core team, or someone picked by the core team.  This is not to
@@ -843,9 +856,6 @@ break other code, that it follows the documentation and existing
 proposal.  It is to check for possible optimizations or better ways of
 doing it.
 
-For members of the core team, one or more other members of the team will
-perform the review.
-
 Note that all code is expected to follow the coding principles and style
 guide contained in this document.
 
@@ -867,7 +877,28 @@ is a good chance it will not be dealt with.
 Send patches to rt-<major-version>-bugs@fsck.com, too.  Use C<diff
 -u> for patches.
 
+=head1 SCHEMA DESIGN
+
+RT uses a convention to denote the foreign key status in its tables.
+The rule of thumb is:
+
+=over 4
+
+=item When it references to another table, always use the table name
+
+For example, the C<Template> field in the C<Scrips> table refers to
+the C<Id> of the same-named C<Template> table.
+
+=item Otherwise, always use the C<Id> suffix
+
+For example, the C<ObjectId> field in the C<ACL> table can refer
+to any object, so it has the C<Id> suffix.
+
+=back
 
+There are some legacy fields that did not follow this rule, namely
+C<ACL.PrincipalId>, C<GroupMembers.GroupId> and C<Attachments.TransactionId>,
+but new tables are expected to be consistent.
 
 =head1 TO DO