Contributing Patches

It is about trying not to do too much.
Do little but do it well.

This contribution guide helps you to get started contributing to WackoWiki development.

1. How to contribute

There are several ways for developers to contribute to the WackoWiki project.


  1. Give us feedback about the software: what you like, what you don't like, features you like to be added in new versions, comments on documentation, etc.
  2. Develop new features: Have a look at the bug traker. Simply pick one of the open tasks and start working on it.
  3. Find a bug, submit the bug to the bug tracker at https://wackowiki.org/bugs/. If you've already solved the bug and are willing to share the fix, please add a patch to the issue.
  4. Submit a patch or make a Pull-Request to the patch manager of WackoWik if you have developed some new features. The submitted patch should follow the coding and templating standards described in this document.
  5. Documentation: there are some parts of WackoWiki that are not very well documented. Refer to the bug traker for a list of open tasks.
  6. Localization: The user interface of WackoWiki is now almost completely localized. If you'd like to translate WackoWiki to a new, not yet supported language, you can refer to the localization "how to" document to understand on how to add a new language.

Development Tools are:

1.1. Committers Licenses

The only acceptable license for code committed to WackoWiki Core is the New BSD License.

1.2. Discuss your design

The project welcomes submissions but please let everyone know what you're working on if you want it to become part of the main repository.


Before undertaking to write something new for the WackoWiki project, send mail to the mailing list to discuss what you plan to do. This gives everyone a chance to validate the design, helps prevent duplication of effort, and ensures that the idea fits inside the goals. It also guarantees that the design is sound before code is written.


In short, send mail before you code. And don't start the discussion by mailing a change list!

1.3. Patches

Each problem should be solved in a separate patch. To allow easy maintenance of patches, every patch should have a header providing the following information:

  • Authors' names
  • Detailed description of the fixed problem

The name of a patch file consists of:

  • The name and version of the source from which the patched file is derived
  • Some words that characterize the patch content
  • The filename suffix .patch

2. WackoWiki repository

You can gain commit access if you prove yourself worthy by sending good patches regularly.


public

  • stable
  • dev

Set up a personal repository other developers can pull from.


personal

  • team member
  • contributor
    • topic branch

2.1. Anonymous access

You can check out the WackoWiki repository through anonymous access following the instructions below.


  • Download and install mercurial.
  • create your (local) repository
  • Get the source:
    • https://bitbucket.org/wackowiki/wackowiki-stable
    • https://bitbucket.org/wackowiki/wackowiki-dev

2.2. Personal repositories

You can set up your personal repository on your own server or on one of the public Source code hosting like Bitbucket or SourceForge (user repo).

  1. sf.net -> register -> add personal repository
    • e.g. http://sourceforge.net/u/USERNAME/code/ci/tip/tree/
  2. Mercurial Hosting – Services that provide hosting of Mercurial repositories.

2.3. Modules in repository

The following modules are available within the WackoWiki repository.

3. Collaborative Development Models

  1. The Fork + Pull Model lets anyone fork an existing repository and push changes to their personal fork without requiring access be granted to the source repository. The changes must then be pulled into the source repository by the project maintainer. This model reduces the amount of friction for new contributors and is popular with open source projects because it allows people to work independently without upfront coordination.
  2. The Shared Repository Model is more prevalent with small teams and organizations collaborating on private projects. Everyone is granted push access to a single shared repository and topic branches are used to isolate changes.

Pull requests are especially useful in the Fork + Pull Model because they provide a way to notify project maintainers about changes in your fork. However, they’re also useful in the Shared Repository Model where they’re used to initiate code review and general discussion about a set of changes before being merged into a mainline branch.

3.1. Fork + Pull Model

  1. Create a fork of the repository. Go to the repository that you want to fork. This gives you a copy of the code from the point where you fork it.
  2. Clone your new fork. Now you may clone your new repository, to create a local copy.
  3. Work on the files locally. Edit the files, add new files, and so on. It is your repository.
  4. Commit change sets to your local repository as usual.
  5. Push your changes up to your fork. Push your changes to Bitbucket in the usual way. This will update your fork of the repository.
  6. Send a pull request to the owner of the original repository. Once you are satisfied with your changes, you can ask the owners of the original repository to pull in your changes and merge them into the main repository. Send a 'pull request'. The Issue tracker will send a notification to the owner, making it easy for you to communicate with them about your changes from this point onwards.

3.2. Shared Repository

-> see Workflow

4. Code Conventions

-> see Code Conventions