Tags:
dev_essential2Add my vote for this tag development1Add my vote for this tag process2Add my vote for this tag create new tag
, view all tags

Developer Responsibilities

With every freedom comes responsibilities, and if you are able to check in you also have a responsibility to contribute to the maintenance of the repository. Below is a list of the responsibilities that come with checkin access. If you cannot agree to this list, then you should not ask for checkin access.

Subscribe to the twiki-dev mailing list

So you can follow changes in the core and standard plugins. In addition there is an RSS feed (see SubversionReadme), and the #twiki-dev IRC channel on Freenode. To subscribe to the list see TWikiDevMailingList.

Tell others what you are doing

Bugs must be reported and tracked in the Bugs web. New ideas and enhancements should be explored in the Codev web, by raising a FeatureRequest. When common understanding and agreement is reached, the work should be broken down into individual tasks that can be added to the Bugs web.

If you want to check in code to the TWiki Subversion repository, create a TWikiGuestWouldLikeToCheckIn topic (see RequestAccessToSubversion), describing why you are wanting access to the repository.

Follow the checkin process

Update before you check in

You must always "svn update" before you check in, to ensure you are using the head of the branch. All hell will break loose if you fail to do this.
svn update
(this will report the pre-checkin version number of the repository)

Test your code

And what may seem obvious but it often omitted. Test your new feature or bug fix carefully. We see too many checkins where 30 minutes of plain functional testing of the new or fixed feature would have revealed very basic errors.

The Subversion repository is a community resource that many depend on and a broken code base can block others from getting their work done. Subversion is not a scratch pad for half finished code. You are supposed to check in code which is well tested and fully functioning. If you are implementing a large chunk of code then either divide it up in small pieces that can be committed as fully working pieces or wait till the work is finished.

Run the unit tests and integration tests

There are unit tests (see test/unit/README) and integration tests (in the Testcases web). Many plugins and contribs also have unit tests. Run them - they are there for a reason. If they break as a result of your change, find out why and fix it. If the tests don't run on your platform, find out why and fix it.

Label your commits

When you check in, you must provide a log message describing the commit. This log message must start with the name of the Bugs web topic that documents the change (this is known as the label). Examples:
svn commit -m "Item666: changes to support slicing of bread using TWiki"
svn commit -m "Item678: the yoghourt slicer now handles peach melba correctly (thanks !MarthaStewart)"
svn commit -m "Item682: reverted change that breaks wikiwords"

Commits without an appropriate label MUST be removed - if you find that someone has failed to label a commit, then either fix it or roll it back. You don't need to ask anyone's permission.

Incorporating third party code

Incorporating third party code is OK. The following guidelines need to be observed:

  • Comply with the GPL (GnuGeneralPublicLicense)
  • Attribute the contributor of the third party code.
  • If the third party contributor has a TWiki.org account use the WikiName of the person in the commit comment; else use the first name and last name.

Review what you have done

svn log -r 123

Document your changes

Provide documentation that is in line with the TWikiDocsStyleGuide. This step is crucial.
  • If there is existing documentation that you need to modify, do so in the version in your checkout area and commit the changes at the same time as you check in the code.
    • If you use TWiki to edit documentation, make sure ^Ms are removed and the TOPICINFO is reverted to author="TWikiContributor" and version="$Rev$ before check-in.
  • You can also write the documention in your ChangeProposal topic, indicating where it should go. e.g: TopicCreateDateInFormattedSearch. Eventually. (ALERT! the chances of documentation done this way getting merged correctly are very small; it is much better to change the SVN docs)

Test and review at regular intervals

It goes without saying that all changes should be tested before, and preferably after, check-in. As well as that, you should continuously monitor the health of the repository. The easiest way to do this is to use the TWiki version that is kept continuously running on the code at the head of the repository, at Bugs:WebHome. Alternatively you can run your own version off the code on the SVN trunk. Even if you are not making changes yourself, other people are, and need your feedback on their changes.

If something breaks, fix it

If a change is committed that breaks the code at the head of the branch it is the responsibility of every member of the community to correct the problem. It is never someone else's problem (even if they broke it) it is always your problem.

This however does not mean that you can check in untested and maybe broken or half finished code and expect the community to fix it for you.

Revert your changes that are inappropriate

If you submit a change that is subsequently felt by consensus to be inappropriate, or inadequate, or anti-mission. then you are responsible for removing that change from the repository. The revision number you recorded in the ChangeProposalForm topic when you checked in can be used to isolate the changes you made. You must then revert these changes, check in again, and update the ChangeProposalForm topic describing what you did, why you did it, and the version number of the new revision.

Revert other people's changes that are inappropriate

Sometimes it will not be possible for the original author of an inappropriate change to roll it back. In this event all members of the community have a responsibility to help them out and roll back the change for them. The same process as for rolling your own changes back should be followed.

If you want/need to roll back someone else's changes because they are inappropriate, inadequate or anti-mission, you must try contact them first by posting in the change topic and/or by email (if possible). If you're rolling back some change because it breaks TWiki, you don't need to ask.

Observe the coding standards

Perl coding standards

System Requirements

Core code should be based on the TWikiSystemRequirements.

Avoid adding dependencies on external Perl modules not shipped with standard Perl. This is because TWiki is sometimes used in intranet environments where Internet access is difficult or non-existent, making it hard to install add-on modules directly from CPAN. Also, someone installing TWiki is often not the server administrator, requiring someone else to perform the module installation (or a more complex CPAN configuration) - this applies to intranets and TWikiOnWebHostingSites. You can check which modules are available in which perl releases by looking at the perl module on CPAN.

If you find you do have to add a dependency from core code on an external perl module, make sure it is discussed to death on Codev first.

TWiki Coding Conventions

Please follow these coding conventions when contributing to core code. This is to make source code more consistent and readable. Please provide your feedback in CodingStandardsDiscussions.

Note: the general rule is that readable code is more important than slavish adherence to coding standards. The format of the POD headers for exported functions is important, though, as they are automatically extracted to form the source code documentation in the release.

  • use strict
  • use warnings
  • use Assert
    • This defines ASSERT, a function that causes a die if a condition is false. ASSERT is used as follows: ASSERT( $condition ) if DEBUG; This is conditionally compiled i.e. is enabled only during development.
  • Function names:
    • Use bumpy words that start with lower case, i.e. sillyOperation
    • Prepend private function names with _, i.e. _secretOperation
  • Function documentation:
    • Use the documentation templates below for header documentation for functions.
  • Variable names:
    • Use bumpy words that start with lower case, i.e. $sillyVariable
    • Always initialize, even if it's to undef.
    • Avoid global variables like the plague, to avoid problems with mod_perl
  • White space:
    • Follow the style of the current Perl scripts for indentation (four characters per level of indent), spacing around brackets and placement of braces (e.g. of '{}')
    • Use only spaces for indent, don't use tabs. Mixing tabs and spaces often causes problems, especially with patches. To simplify doing this with specific editors, see VimEditor, EmacsEditor, ...
  • Comments:
    • Use comments to describe what you are doing where appropriate
    • Special comments: In case some parts of your code need later attention, state that in your comments as:
      • # SMELL: for unclean code that looks like a bug, or violates common coding practices, or misses some corner case

Example package header

=pod

---+ package TWiki::Vector
Objects of this type represent 3D vectors

SMELL: quaternions are more flexible

=cut

package TWiki::Vector;

Example Class Method

A class method is an OO static method that is invoked using indirection off the package object e.g. TWiki::Vector->new() or new TWiki::Vector()

=pod

---++ ClassMethod new( $x, $y, $z )
Constructor for a new vector object
   * =$x= - X component
   * =$y= - Y component
   * =$z= - Z component

=cut

sub new {
    my( $class, $x, $y, $z ) = @_;
    my $this = bless( {}, $class );
    $this->{x} = $x; $this->{y} = $y; $this->{z} = $z;
    return $this;
}

Note how $class is not listed in the parameter documentation.

Example Object Method

An object method is a OO method that is invoked using indirection off a blessed object of the package type e.g. my $c = new TWiki::Coord(1,2,3); $c->normalise(); or TWiki::Coord::normalise( $c )

=pod

---++ ObjectMethod normalise() -> $length
Normalise the vector to have length 1 i.e. become a direction vector.
Return the magnitude of the original vector.

=cut

sub normalise {
    my( $this ) = @_;
    ASSERT( $this->isa("TWiki::Vector") ); # it is always best to make sure....
    my $mag = sqrt( $this->{x} * $this->{x} + $this->{y} * $this->{y} + $this->{z} * $this->{z} );
    $this->{x} /= $mag; $this->{y} /= $mag; $this->{z} /= $mag;
    return $mag;
}

Note how $this is not listed in the parameter documentation.

Example exported static method

Header for a static method intended to be visible outside the package. A static method is any non-OO method.

=pod

---++ StaticMethod dot( $vectorObject, $vectorObject ) -> $number
Return the dot-product of two vectors.

=cut

sub dot {
   my ( $a, $b ) = @_;

   ASSERT( $a->isa( "TWiki::Vector" )) if DEBUG;
   ASSERT( $b->isa( "TWiki::Vector" )) if DEBUG;

   return $a->{x} * $b->{x} + $a->Py} * $b->{y} + $a->{z} * $b->{z};
}

Private methods

headers for private methods (private class methods, static methods and object methods) should follow the same pattern as exported methods except that they should be documented using # comments rather than POD. For example,

# ---++ ObjectMethod _crush( \@x ) -> $boolean
# Crush the vector with an array.
# Note use of \@ to indicate an array reference
# Note also use of $boolean to indicate the result type.
# Remember that undef, "" and 0 are all FALSE in perl, and any non-zero number or non-empty string is TRUE.
sub _crush {
   my( $this, $x ) = @_;
   ASSERT( ref($this) eq "TWiki::Vector" );
...

Internationalisation support (NEW)

See: InternationalisationGuidelines

You don't need to know anything about internationalisation (I18N) to make your code work with international characters in WikiWords and much more, and it also makes your code more readable. The guidelines cover both core code and plugins.

Tool Support

Options to ensure consistent formatting:

CSS coding standards

See: CssCodingStandards

JavaScript coding standards

See: JavaScriptCodingStandards

Know how to use your tools

Contributors:
-- CrawfordCurrie, RafaelAlvarez, PeterThoeny

Discussions

You don't say anything about "use warnings;" in the coding standards, yet warnings is considered by most master perl programmers to be critical to producing maintainable perl code. As someone new to the TWiki community (although a long-time perl geek), I'm not so much objecting to the decision as surprised at the lack of any mention of why...

-- HilaryHolz - 01 Aug 2008

Hilary - wow - what an omision - mostly its because we've forgotten that anyone would write code without turning warnings on. I've added it.

-- SvenDowideit - 02 Aug 2008

I like this page, because it helps to foster new code commits by new developers. That is what we need. Thanks to all the contributors for this topic.

-- MartinSeibert - 02 Aug 2008

Edit | Attach | Watch | Print version | History: r56 < r55 < r54 < r53 < r52 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r56 - 2008-11-23 - PeterThoeny
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.