Plugin contribution

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

This page describes the various ways to share and work collaboratively on add-ons, previously known as contributed plugins or contributed code.

The process

Sharing code - Add-on code will be shared and maintained using a public Git repository (i.e. github.com, gitorious.org, etc.). If you are not yet familiar with Git, it is recommended that you learn Git basics. The nice thing about using Git is that it will leave control of the code in the hands of contributor.
Reviewing code - If you would like your code to be tested and reviewed, please create an issue in the Moodle Tracker under CONTRIB.
Documenting code - You can maintain helpful documentation of the features and installation instructions in Moodle Docs
Distributing code - You can help others find your code by registering your plugin in the Moodle plugins directory.
Discussing the code - You can discuss the functionality and answer questions about how to use your code in the Using Moodle forums. Users can ask questions, discuss possible ideas for improvement, etc. Once the discussion matures to a point where you may want to take action, then you can create an issue in the Moodle Tracker.
Maintaining code - You can further develop your code by fixing issues, adding features, and responding to other issues with the Moodle Tracker. Each plugin or patch can have its own component in the CONTRIB project; however, you will need to request that the component be created in the CONTRIB project. Once created, users can easily create issues related to your add-on code. The primary maintainer of the code will be assigned as the component lead and have their tracker privileges bumped so that they can manage issues related to their code. Those issues will automatically be assigned to the component lead/primary maintainer.

The Add-on Frequently Asked Question (FAQ)

Question: I have written a new add-on to share with the Moodle community. What is the process for contributing the code?

Answer: First, thank you for your generosity and desire to share your work with the rest of the Moodle community. Code contributions are highly valued and Moodle wants to encourage creativity and generosity in keeping with Moodle's social constructionist pedagogy.

As mentioned, there are various tools to help you share and support your contribution. By using a consistent methodology, your Moodle related code will be more easily found, tested, used, maintained, documented, and evaluated by fellow Moodlers and developers. Learning to use the various tools common among Moodle developers will help you to efficiently and effectively develop, share and maintain your add-on.

How to submit code

You have created some code that you would like to contribute to the Moodle community. The first step is to choose which Git code hosting site you want to use. Both github.com and gitorious.org are popular. Follow the instructions for creating a public repository for your code. This will allow others to download your code as well as suggest possible patches. As you become more familiar with collaborating with others you can also control who else you want to be able to push changes into your repository (i.e. write access).

In order to facilitate a common naming convention of Moodle related repositories, it is suggested that you use the following format: moodle-{plugintype}_{pluginname}. For example, the birthday block has a repository name of moodle-block_birthday and is located at https://github.com/arborrow/moodle-block_birthday. Other developers can fork the code and work from their repositories.

How to request that your code be tested/reviewed

If you do not already have an account on the Moodle Tracker, create one and login.
Create a new "Task" issue in the "Non-core contributed modules" project, selecting 'Add a project here' as component. Your issue will be a request that the code be tested and reviewed.
Provide the link to the repository (i.e. https://github.com/arborrow/moodle-block_birthday)
Provide a clear description of what the code does and the functionality that it adds to Moodle.
Provide any other links to supporting documentation

The Contrib Coordinator will then work directly with the code contributor via the Tracker to help evaluate the code, work on resolving any questions/issues found, etc.

Contributors are encouraged to follow Moodle's coding guidelines Coding.

Contributors are encouraged to maintain a branch for each major Moodle release (i.e. 2.3, 2.4 etc.). The HEAD branch should be used as the development branch.

Contributors are encouraged to associate each change made to an issue in the tracker. This practice is done by Moodle core developers and it is a good habit to get into so that you can go back and see why various changes were made to the code. Simple practices like these help to create good documentation of the code as it develops and matures. Commits should begin with the Moodle tracker issue number followed by a brief description of the change.

How to provide documentation

Having great code available to the community is wonderful. It is also important to educate users about how to use the code with documentation in Moodle Docs. See Plugin documentation for details.

Share code in the Moodle plugins directory

Now you have a place for users to get your code, how will they know it exists? Please register your add-on in the Moodle plugins directory.

Users may leave comments on your entry, so please check it periodically for questions and bug reports. If you include contact information or a link to a discussion, your users may be able to contact you more directly.

Keep in mind that plugins added to the Moodle plugins directory have to pass both an automatic and a manual validation process before they will be visible to other Moodle users.

If you are using git to store your code, you will need to export the repository cleanly into a zip file containing one folder, named after your plugin. Use this code to do that:

 git archive -o path/to/filename.zip --prefix=yourpluginname/ yourbranchname

Support code and get feedback with forums

As users become familiar with the add-on, discussions about the code are likely to emerge. We strongly urge you to place links to at least one forum at moodle.org in your plugins directory entry as well as in Moodle Docs.

It is important to respond to users who have questions about how to use the code, suggestions for how to make it better, etc. If an add-on maintainer thinks there is sufficient need for their add-on to have its own forum, they should create a Moodle Community Sites issue for it in the tracker.

General add-ons forum is a generic forum. Be sure to put the add-on name in the discussion title.
Using Moodle forums The English forums on moodle.org
Full list of courses on moodle.org

Maintain and refine code using the Tracker

In order to facilitate keeping track of feature requests, bugs, and other code issues, the contributor may request that a component be created in the CONTRIB section of the Moodle tracker.

The contributor can be added to the group of CONTRIB developers in the tracker to manage the issues assigned to them and better coordinate with other developers. Add-on users can then add issues which can be assigned directly to the maintainer. The tracker helps to manage the work flow involved in fixing bugs, working through feature requests, and maintaining the code. When committing changes, maintainers are strongly encouraged to begin the commit comment with a tracker number.

We strongly encourage users to involve themselves in the process of creating a useful issue in tracker. For the developer and code contributor, describing the fix can help clarify the need for the code change. Further, it helps to establish good documentation about how the code developed. Others will be able to identify the issues addressed and understand why a particular decision was made.

Summary

It is hoped that following this procedure, will help guide contributors of code in the process of learning the tools and skills used by the Moodle developers. Learning to submit code by using the tracker, work the code with Git, support the code by providing documentation, share code in the plugins directory, maintain the code by using the tracker, and evolve the code by using the Moodle.org forums will assist you in successfully contributing to the Moodle community and working with Moodle's developers.

Throughout this process, the CONTRIB Coordinator is here to encourage and support those contributing code to the Moodle community and fostering the development of tomorrow's Moodle developers.

Eventually, the community may wish for the code to become part of the Moodle core. By following the steps above, the developers will be able to evaluate the merit of the add-on, understand how users have used the code, see the issues that have emerged and thus have more information to make an informed decision about whether or not to incorporate the add-on into the standard distribution.

Documentation