Readme First for TWiki Developers
The Codev web is the place where discussion is held on the development of TWiki. Everybody who is interested in contributing to enhance TWiki is invited to collaborate in this Codev web. You can subscribe in WebNotify
page to get daily email with all changes in Codev web. See also our TWikiMailingLists
and subscribe to lists of interest. The TWiki community operates under a TWikiGovernance
modeled after the successful Ubuntu community.
How to Find, Where to Post
The Codev web is several thousand pages, and growing every day. For the unfamiliar, it can seem a little daunting to try and find specific info, or figure out where to post. Not so! Although wikis are constantly in the midst of cleaning and decluttering, Codev is a most orderly place. Here's the how-to:
- Searching is fast, comprehensive, easy: In fact, those are core TWiki design specs. Use the Search box on the toolbar at the top of every page.
Hint: To get a list of topics on a subject like "xml", type the name into the Jump box. It's fast and easy.
- Check under Codev categories: The Codev web has a set of Categories that link to a quick-scan list of Codev page categories. Codev topics may be classified: click on a heading to get full list topics. (And you can come straight back to this page from the toolbar, too!)
- Browse from page to page: Less structured than searching and clicking categories, but often more useful, simply start on a page that interests you, and follow the inline links - a major Wiki feature is the use of meaningful, easily-created WikiWord links in the text, leading to all sorts of cross-topic threads!
POSTING is easy once you know the Codev setup:
- Start from WebHome: On the Codev home page, you'll find the topic categories, along with other key pages, some of which change over time: special projects, announcements, new release notices, and more. All fully described. Click Codev on top of that left toolbar.
for a basic text entry primer. Click
and you're off. You'll see a WebForm
with the page classification: change it if it's wrong, fill it in for a new page. The CodevCommunity
has a SignatureNetiquette
. Use your judgment whether to add to an existing discussion, or start a fresh topic. It's that simple.
"TWiki, the open source Enterprise Wiki and Web 2.0 Application Platform."
- Many small steps
- Evolution is preferred over revolution
- Maintainable source
- Follow CodingStandards, write clear, descriptive comments, use intention-revealing naming and simple and obvious structure
- Architectural integrity
- Don't just hack in fixes; go the extra mile to make them fit
- Maximize test coverage
- Test everything, and automate tests wherever possible
- Tests must pass
- If the tests ever fail, drop everything and fix them
- High production quality gates
- Functional elegance
How Can I Contribute?
TWiki is an Open Source project, and as such relies on the support of users and fans to keep going. So anything you can do to help, is almost certain to be welcome!
There are many ways you can contribute, from simply telling the community your story, through helping support other people, or even becoming a fully-fledged down-and-dirty developer. Here are just a few of the more obvious ways you can contribute.
| Be an advocate. Tell your friends, tell your colleagues, present papers, use the tool, wear the T-shirt!
|| Tell the community your success story. Write a page starting with the words "TWikiSuccessStory". There are lots of examples already there!
If your story isn't a success - and we all know there are some - it's still equally valuable.
| Help out with documentation. If you find problems with the documentation, or find it difficult to use, or simply can't find the answer you were looking for, then don't just complain. Go fix it as well! You can contribute documentation updates just by creating a topic in this web with your proposed change or, better, by raising an item in the Bugs web.
|| Crush bugs. Bugs get reported in the Bugs web. If you are adventurous, you might try your hand at finding a fix, and post that alongside the report! The more relevant information you provide with the report, the more chance there is of there being a fix. Don't forget that your bug may have been reported already, and there might even be a patch to fix it. If you know how to fix a problem, you are very welcome to attach a unified diff to your report (but please make sure it's clear what version of the code it's based on!)
| Be a support god. The Support web is full of questions that need to be answered. If you are confident enough, feel free to answer any that you can! The support web is an entirely volunteer effort, so the more people who visit and help out, the better. It's a really good way to keep your finger on the pulse of TWiki activity in the real world. TWikiIRC is also a great place to help people, discover features that you never knew existed, and to meet and influence others. A lot of new users find their way to IRC, and there's a lot of friendly and knowledgeable people who hang out there too.
|| Contribute brainpower. The Codev web is a fertile ground for the seeds of ideas. It's made fertile by the many eyes who read changes to topics, and contribute to the development and refinement of ideas into reality. This isn't onerous; it just means staying aware of what's being discussed and when you think you can contribute, being prepared to speak up. Contributing doesn't just mean voicing opinions, of course. The goal is to refine ideas down to practical solutions, and that requires a positive outlook, and a preparedness to get your hands dirty, even if it's only to refactor (organise) a topic.
And don't forget; the newest contributor often has the freshest ideas!
| Write/maintain extensions. The most common way to get started coding TWiki is to contribute to the Plugins repository. Extensions are extra modules that can be plugged in to TWiki to support - for example - application integrations, new functions, and TWikiApplications. You can also contribute skins, which are tailored look-and-feel modules. Some extensions are contributed to the repository, but their original authors don't have the time to maintain them properly, so maintainers are always welcome too.
See SoYouWantToBeATWikiDeveloper for help in getting set up. Core developers and extension developers can RequestAccessToSubversion to maintain code directly in Subversion.
|| Develop new features. You don't necessarily need Perl skills to develop TWiki features. Many features have been contributed by people working in other areas, such as translations and TWikiApplications. See TWikiFeatureProposals for the community wishlist, and see where you can help!
| Join a Task Team. Task teams are groups of people who undertake larger chunks of work within the TWiki project. Task teams are largely independent, self-governing, mini-projects set up by like-minded people to get things done. Examples of task teams can be found at TaskTeamExamples. Anyone can form a task-team.
How Can I Start Contributing Code?
for a detailed list on what to do to get started as a contributing TWiki developer. Core developers and extension developers can RequestAccessToSubversion
to maintain code directly in Subversion.
Types of TWiki Releases
There are two ways you can get TWiki. You can use a TWikiProductionRelease
or, if you are a bit brave, you can check out the subversion repository and run TWiki on top of that. Developers sometimes create branches for testing that you might want to use as well.
Release Naming Convention
TWiki uses the GNU "standard" for naming releases, e.g. TWiki-4.9.36
. The first number is a major release identifier which changes when major new features or technology is introduced. the second is a revision for minor releases where smaller evolutionary features are added, and the third is a patch level. Patch releases only contain bug fixes, and the goal is that you can throw the files that changed on top of a live running installation of TWiki without having to setup anything again afterwards.
Typical work-flow for new features
- Developers discuss new features in the Codev web, one topic per feature. You both create and see existing feature proposals on TWiki Feature Proposals.
- The decision process is described in TWikiReleaseManagementProcess.
- When a proposal is accepted the committed developer(s) creates one or more new entries in the Bugs web, and marks the Codev topic as UnderConstruction.
- The code is incrementally checked into Subversion, so other developers and testers can see it in progress and add their comments/code.
- All new end-user features should be documented in TWiki web, the place for end users and TWiki administrators.
- Tracking is done in the Bugs web, and when the feature is finished the Codev topic is set to MergedToCore.
- Remember, a feature isn't done until it's all done - doc and unit tests as well!
Feedback is appreciated in ReadmeFirstFeedback
(and in CodingStandards
for that matter)
-- Contributors: PeterThoeny