Perlwikibot/Contributing

From Wikibooks, open books for an open world
< Perlwikibot
Jump to: navigation, search

Introduction[edit]

Perlwikibot is an open-source project which aims to create a complete framework for rapidly creating and deploying computer programs which can perform common repetitive tasks on MediaWiki wikis. These clients are typically called 'bots' - hence the project name.

You can help fix bugs or add new functionality to the framework. The code is licensed under the GNU General Public License. In short, this means anyone may use the code for any purpose, including commercial use, and including making and distributing modified versions so long as they provide attribution and all derivative versions are also licensed under the GPL.

Code style[edit]

Perl code is hard enough to read already, so try to make an effort to write readable code.

Comments[edit]

Comments should be included wherever the code does something that isn't obvious.

bad
sub foo {
    my $param = shift; # Take the first param
    my @args = @_;     # Take the remaining elements, if any
}
good
sub bar {
    my $param = shift; # The page to edit
    my @args  = @_;    # Contains any other settings (for example, whether to mark the edit as minor)
}

Perltidy[edit]

Perltidy is a code indenter and formatter. You can use it to help clean up your Perl code. For perlwikibot, use:

-syn    # Syntax check input and output
-b      # Backup and modify in-place
-l=78   # Max line width is 78 cols
-i=4    # Indent level is 4 cols
-ci=4   # Continuation indent is 4 cols
-vt=0   # Minimum vertical tightness
-vtc=0  # Minimum vertical tightness closing
-cti=0  # No extra indentation for closing brackets
-pt=2   # Maximum parenthesis tightness
-sbt=2  # Maximum square bracket tightness
-bt=1   # Medium brace tightness
-nsfs   # No space before semicolons
-nolq   # Don't outdent long quoted strings
-boc    # Break at old comma breakpoints
-bbs    # Blank line before subs
-sot    # Stack opening tokens
-sct    # Stack closing tokens
-bbao   # Break before all operators

You can put this in .perltidyrc, and they'll be used every time you use perltidy. Put the file in your working directory to apply only to that directory, or in your $HOME to use the settings for everything.

Alternatively, set each option as a command line option to perltidy:

user@host:~$ perltidy -syn -b -l=78 ...

Committing[edit]

Getting commit access[edit]

Ask for commit access on the mailing list.

Checkout[edit]

Find instructions at [1].

user@host:~$ svn checkout http://perlwikipedia.googlecode.com/svn/ perlwikibot

Commit[edit]

Find instructions at [2]. Your password is available on the Settings tab of your Profile page (link in top-right corner).

user@host:~$ svn checkout https://perlwikipedia.googlecode.com/svn/ perlwikibot --username $username
# Enter your password
# hack hack hack
user@host:~$ svn diff
user@host:~$ svn commit

Maintaining ./trunk/Changes[edit]

The Changes file is for major things that the user will want to know about. If your commit fixes a bug or adds a feature, update Changes, if you commit fixes formatting, adds documentation, or adds or edits tests, don't bother with the Changes file. The Changes is meant to be a way for a user to see what changed when they update without looking into the repository.

When you fix a bug or add a new feature, add a note to the "unreleased" section in ./trunk/Changes in the same commit. If there is no "unreleased" section, create one. When the next release is made, the release manager will move all the notes into a release section and create a new section for changes to be added to for the next release.

Using git-svn[edit]

Everyone hates SVN, but sometimes you have to use it. git-svn might make using SVN more palatable, though it isn't a cure-all.

The perlwikibot repository is quite small (<300 commits as of May 2010), so you should have no problem making your own clone:

user@host:~$ git svn clone http://perlwikipedia.googlecode.com/svn/ perlwikibot
# wait, wait, wait
# still waiting, SVN is horrid isn't it?
# hack hack hack
user@host:~$ git commit ...
user@host:~$ git svn dcommit

Don't use git branches, SVN doesn't understand them and you'll get useless commit messages like "Merging branch 'feature_branch'" instead of your real commit message. If you figure out how to make git branches and SVN play nicely, update this page!

Mike pushes his git repo to github; do with it what you will.