Help on getting started as a developer

Developers don't just write code. Translators are also developers, as are documentation authors, skin designers - anyone who contributes to a release package is a developer. This is the starting point for the documentation that is useful mainly to developers.

TIP You can tell when you are in a developer documentation topic because it will have the DNA logo you can see above. You can see a list of the developer documentation pages used day-to-day in the developers bible.

There are two types of developer; core developers, who are brave/stupid enough to make changes in the core, and extension developers, infinitely more sensible people who work on the edges, producing plugins, skins and other types of extensions.

At this point you are recommended to review the technical overview before proceeding any further. That should help you decide what sort of developer you are.

If you see yourself as an extension developer, and are in a hurry to get started, then read the Extension Developer Guide.

Core developers have to work in the git repository, and many extension developers choose to work in git as well, as it's much safer and more... well, community-minded. You don't have to use the repository if you are developing an extension, but you are strongly recommended to do so. HowToStartExtensionDevelopmentInGit has a detailed guide explicitly for extension authors.

The topic GitBasedInstall describes how you can checkout the code (core and extensions) from git and install it (pseudo-install) so you both develop and test on a git checkout. If you want to be a developer, getting a pseudo-installed Foswiki working is one of the first things you want to do.

We do most development on the git master branch of the distro repository - default extensions and core together in the same repository. Anyone wishing to check in has to get added to the list of Core developers. Unfortunately we have to do this, because of the risk of vandalism. However the process is very simple:
  1. Read DeveloperResponsibilities to fully understand what you are getting into.
  2. Read the CopyrightAndLicense if you have questions about the licenses that apply to Foswiki, and how they might read onto your work.
  3. Create an account on https://github.com/ If possible use the same email address you used when registering on http://foswiki.org, And/or use your name in the github registration in a form that can be converted to your WikiName. When you author a change on github, we'll use your github email & user name to match up on foswiki.org for the task update.
  4. Create a topic in this web called "YourWikiNameWouldLikeToCheckIn" using the form on RequestAccessToGit. In this topic, describe who you are, a little bit about your background, and what you think you can contribute.
  5. Your topic will be acknowledged. There's usually then a one-week wait to give existing developers a chance to review the request.
  6. Existing developers have the right to veto anyone being granted access, but they won't do this unless they have a very strong reason.
  7. Checkin rights can be granted by any existing authorised checker-inner (see RingOfTrust), but they can't just add their friends - they must go through the process, or they risk losing their own check-in rights.
Even before you get checkin rights, you can check out the git repository and start developing. Just fork the foswiki repository and submit pull requests to the Foswiki developers. See the GitRepository and GitBranchingAndTagging to understand how the git branches are used to develop different Foswiki releases.

The BuildContrib is an important tool used in Foswiki development, especially for extensions (plugins, skins etc) developers; you should read up about it. UnitTests describes how to start writing Foswiki unit test cases.

Developer Communications

  1. All developers, core and extensions, are recommended to subscribe to WebNotify, in order to be notified automatically when something changes in the Development web.
  2. You should subscribe to the MailingLists for checkin notifications and occasional conversations among developers.
  3. We have one IRC channel: #foswiki carries general discussions, and is often the best place to get support (see Internet Relay Chat for more info).
  4. Requirements, proposals and bugs are tracked in the Tasks web

Repository Access

If you have been given write access to the git repository, you should login to github using your github account and use those credentials to push to the foswiki repository.

Getting a Foswiki development environment up and running quickly

For a two commands installation environment with all the needed dependencies, you can check EasyDevelopment topic. Next is the classical way.

TIP *Foswiki 2.0 install ... covered below, is new. There is a new bootstrap process which tries to guess most configuration settings.

Step Action Example
1 Get a git checkout as described in GitRepository git clone https://github.com/foswiki/distro foswiki
2 Enter the foswiki core directory cd foswiki/core
3 Install the default and development extensions perl -T ./pseudo-install.pl developer You can most likely ignore dependency errors, pseudo-install doesn't install extensions in dependency order.
3a Optional Run rewrite_shebang to fix scripts cd tools && perl -I ../lib rewriteshebang.pl
4 Run the test lighttpd webserver. You need to have lighttpd installed tools/lighttpd.pl
5 Browse to the default page, triggering bootstrap: http://localhost:8080 This should guess all the settings and automatically log you in as admin.
6 Follow the link at the top of the page to bin/configure. You should click this link directly, don't edit your URL. It might use URL parameters to set some defaults guessed specifically from the view url you entered
7 Review any errors reported in the configuration.
8 (optional) Configure who should be allowed to use configure. For example, the superuser admin, and a user JoeUser. If you leave this empty, anyone in AdminGroup will be able to use configure. Security and Authentication -> Access control -> {ConfigureFilter} = JoeUser,BaseUserMapping_333
9 Set an admin superuser password (optional but recommended) Security and Authentication -> Passwords -> {Password} (an Expert setting) Follow [i] example docs
10 Save the configuration!
11 Browse to your fresh working copy of Foswiki at http://localhost:8080/ You should still be logged in as admin. Register your user (set in step 8 above) and add them to the AdminGroup before you log out from admin.
Topic revision: r30 - 17 Jun 2021, MichaelDaum
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy