Working with the Community

From MoodleDocs
Jump to: navigation, search

So you'd like to contribute to Moodle? If you do, then thank you very much. The community appreciates your efforts.

Here is a guide to help you work with the Moodle community.

Contents

What to expect

The goal of the Moodle community is to provide the best possible LMS there is. When you submit a patch (or new module, plugin or filter) for acceptance, it will be reviewed on its technical and educational merits and those alone. So, what should you be expecting?

  • criticism
  • comments
  • requests for change
  • requests for justification
  • silence
  • pointers to another subproject with the same goals

Remember, this is part of getting your patch into Moodle. You have to be able to take criticism and comments about your patches, evaluate them at a technical level and either rework your patches or provide clear and concise reasoning as to why those changes should not be made. If there are no responses to your posting, wait a few days and try again, sometimes things get lost in the huge volume.

What should you not do?

  • expect your patch to be accepted without question
  • become defensive
  • ignore comments
  • resubmit the patch without making any of the requested changes

In a community that is looking for the best technical solution possible, there will always be differing opinions on how beneficial a patch is. You have to be cooperative, and willing to adapt your idea to fit within Moodle. Or at least be willing to prove your idea is worth it. Remember, being wrong is acceptable as long as you are willing to work toward a solution that is right.

Differences between the Moodle community and corporate structures

The Moodle community works differently than most traditional corporate development environments. Here is a list of things that you can try to do to try to avoid problems:

Good things to say regarding your proposed changes:

  • "This works great with 9-year olds for learning X."
  • "This solves multiple problems."
  • "This deletes 2000 lines of code."
  • "Here is a patch that explains what I am trying to describe."
  • "I tested it on 4 different databases..."
  • "Here is a series of small patches that..."
  • "This increases performance on typical machines..."

Bad things you should avoid saying:

  • "This educational theory supports my use model, I feel it in my bones."
  • "We did it this way in WebCT/Blackboard, so therefore it must be good..."
  • "I've being doing this for 20 years, so..."
  • "It makes this proprietary benchmark go faster"
  • "This is required for my company to make money"
  • "This is for our Enterprise product line."
  • "Here is my 1000 page design document that describes my idea"
  • "I've been working on this for 6 months..."
  • "Here's a 5000 line patch that..."
  • "I rewrote all of the current mess, and here it is..."
  • "I have a deadline, and this patch needs to be applied now."

Another way the Moodle community is different than most traditional software engineering work environments is the faceless nature of interaction.

The language barrier can cause problems for some people who are not comfortable with English. A good grasp of the language can be needed in order to get ideas across properly on forums and in the tracker, so it is recommended that you check your text to make sure it makes sense in English before sending.

Consider asking or discussing your proposal first

It is surprising how often a forum posting along the lines of "I wish to propose xxxx" can produce interesting results. You may find that somebody has 95% completed the thing you want to do. You may find somebody has done something similar that you can adapt. You may even have issues raised that you never thought of that may result in a change of direction or abandoning it altogether (a good thing as it can save hours of work).

Break your changes up

The Moodle community does not gladly accept large chunks of code dropped on it all at once. The changes need to be properly introduced, discussed, and broken up into tiny, individual portions. This is almost the exact opposite of what companies are used to doing. Your proposal should also be introduced very early in the development process, so that you can receive feedback on what you are doing. It also lets the community feel that you are working with them, and not simply using them as a dumping ground for your feature. However, don't post 50 times at once in the forums!

The reasons for breaking things up are the following:

  1. Small patches increase the likelihood that your patches will be applied, since they don't take much time or effort to verify for correctness. A 5 line patch can be applied by a maintainer with barely a second glance. However, a 500 line patch may take hours to review for correctness (the time it takes can be exponentially proportional to the size of the patch).
  2. Small patches also make it very easy to debug when something goes wrong. It's much easier to back out patches one by one than it is to dissect a very large patch after it's been applied (and broken something).
  3. It's important not only to send small patches, but also to rewrite and simplify (or simply re-order) patches before submitting them.

It may be challenging to keep the balance between presenting an elegant solution and working together with the community and discuss your unfinished work. Therefore it is good to get early in the process to get feedback to improve your work, but also keep your changes in small chunks that they may get already accepted, even when your whole task is not ready for inclusion now.

Also realize that it is not acceptable to send patches for inclusion that are unfinished and will be "fixed up later."

Justify your change

Along with breaking up your patches, it is very important for you to let the Moodle community know why they should add this change. New features must be justified as being needed and useful.

Consider contributing your work as a plugin

Help with improving core Moodle code is very welcome, however Moodle is designed to be modular, so you should consider sharing your idea as a Plugin. Plugins are shared through the Plugins repository. There are many different kinds of plugins, so check out the guidelines for contributing.

See also

Personal tools
User docs (English)