DRAFT
WikkaCase (Contrib SVN Repository)
About WikkaCase
WikkaCase∞ is a repository of tools and software projects related to
WikkaWiki. Any number of different types of Wikka-related projects can be hosted, including (but not limited to):
- 3rd party software used by Wikka;
- User contributions (skins, actions, handlers, etc.);
- Maintenance scripts and programs
The structure of WikkaCase has been designed to accommodate any type of project or contribution to WikkaWiki, whether just one file or script or a complex plugin or feature.
Setting up a new project
Accounts and projects are set up on an individual basis. You must register an account on the
WikkaCase issue tracker∞, and you must provide us with a valid e-mail address. We will use this e-mail address to send you access information for Mantis and the SVN repository. Please note that at this time, we are not set up for secure transmission of passwords, so please be aware that passwords will be sent "in the clear." Do
not use a valuable password that you don't want compromised!
After registering, submit a ticket in the
Support Requests project. Include the following information:
- Project name
- Project type (action, handler, script, plugin, etc.)
- Project components (every project will have a default "core" component; other components are optional)
- Link to a companion page on the WikkaWiki∞ site (this page will serve as the "entry point" for your project)
Remember that all issues can be viewed by any user, so please don't post passwords or any other private information. Most of the Wikka devs have GPG keys if you need to send us secure information.
Once an account has been set up and your initial project is approved, you will be e-mailed a login ID and temporary password as well as any other instructions for accessing your project. We will also acknowledge project status in the ticket.
Creating tickets
WikkaCase provides each contributor with an issues tracking system for each hosted project that is accessible by everyone. Each project will have its own tracker.
Managing your project
You will be provided access to a Subversion (SVN) repository to manage your project(s). If you're not familiar with SVN, please consult
//Version Control with Subversion∞ before requesting assistance.
All contributors are expected to be familiar with the
Wikka coding guidelines∞. There will be no code reviews (we all have daytime jobs too!), but you will be doing yourself and other Wikka users a great favor by adhering as closely as possible to the guidelines. The easier your project is to install, understand, and maintain, the more likely it is that others will be interested in what you've created.
Using Mantis to manage issues/bug reports
The Mantis manual can be found
here∞.
Source control
For source control, things are a little easier: each project gets its own
project directory at the top level, and below that the standard
trunk,
branches and
tags directories. That way, each project has its own virtual repository, and can be managed as usual. Contributors will have full access to their project directory and any subdirectories.
The first step is to initialize your project with initial directories. After receiving your log in credentials, check out an initial working copy of your new project (in this case, we'll call it
TestRepo) and create the directories you'll need:
svn co https://www.pongonova.net/svn/TestRepo TestRepo
cd TestRepo
svn mkdir trunk
svn mkdir branches
svn mkdir tags
svn mkdir trunk/contrib
svn ci
TODO: Instructions for other SVN clients?
It is important that your project is configured in such a way that a user who checks out your project from the top-level Wikka directory (i.e., the directory containing
wikka.config.php) will find that the files for your project have been installed into the proper directories. Please do
not expect users to copy files from a temporary directory into the proper Wikka directories!
Each project must, at a minimum, be configured with the following directory structure:
- contrib
- projectname
- README.txt (contents TBD)
- (various support files, documentation, patches, etc.)
In addition, your project tree must also contain the Wikka directories that will be used for your project. Please note that Wikka directories change from version to version!
Example 1:
Your project name is
CrazyAction, and it has been developed for Wikka 1.1.6.3. The project files include
actions/crazyaction.php and a CSS file,
css/crazyaction.css. There is also a small documentation file,
crazyaction.txt. Your project tree (the one you check in to the repository) should look like:
A user who checked out your project in their Wikka 1.1.6.3 top-level directory would find that the files to your project have been checked out into the proper directories.
Example 2:
Same project as in
Example 1, except it has been modified for Wikka 1.1.7. This version of Wikka introduces an extra directory layer in
actions:
Documentation
Each project will be required to maintain a companion page on
WikkaWiki. At a minimum, each project must include a link to the SVN repository and a link to the project on the Mantis issues tracker. It is not necessary to have a page for each hosted project (
i.e., a contributor might host several projects on their own personal page). In addition, all contributors will be expected to become familiar with and implement "self-documenting" code via phpdoc (for more details, see the
Code Documentation Tutorial). This will enable the auto-creation of documentation across all projects.
Announcing your releases
TODO: Mabye a dedicated topic on the blog? An announcement mailing list? A "What's New" sidebar on the wikkawiki.org home page with updates to a WikkaCaseProjects page? This one is wide open, folks...