|
|
| (68 intermediate revisions by 14 users not shown) |
| Line 1: |
Line 1: |
| This page describes the various ways to share and work collaboratively on contributed code.
| | {{Template:Migrated|newDocId=/general/community/plugincontribution}} |
| #Submit code in Tracker under CONTRIB.
| |
| #Work with submitted code in cvs.moodle.org
| |
| #Document features, install instructions in docs.moodle.org
| |
| #Share and distribute code with [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins] database
| |
| #Maintain and refine code with tracker.moodle.org
| |
| #Talk and support code within forums at moodle.org
| |
| | |
| ==The Frequently asked question==
| |
| '''Question:''' I have written a new block, activity, patch or theme 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 its constructivist tradition and pedagogical approach. To support this, there are several tools will support your contribution by allowing the code to 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 the contributed code.
| |
| | |
| ==How to submit code==
| |
| You have created some code that you would like to contribute to the Moodle community. The first step is to create a login in [[Tracker]]. You should create a new issue as a "non- core contributed module" project and a "New Feature" issue type. Here is a link to tracker with [http://tracker.moodle.org/secure/CreateIssue!default.jspa?pid=10033 those fields filled in].
| |
| | |
| Your issue will be a request that the code be evaluated and uploaded into CVS. Provide a clear description of what the code does and the functionality that it adds to Moodle. Attach the contributed code as a zip (or tar.gz) file to the tracker issue. At that point, the Contrib Coordinator will work directly with the code contributor to help evaluate the code, work on resolving any questions/issues found, etc.
| |
| | |
| *Contributors are encouraged to follow Moodle's coding guidelines [[Coding]]).
| |
| *A list of current tracker [http://tracker.moodle.org/secure/BrowseProject.jspa contributed projects is here].
| |
| | |
| ==How to work with code in CVS==
| |
| Once the code has been added to the CONTRIB section of Moodle's [[CVS (developer)| CVS]], the contributor will request CVS write access via http://moodle.org/cvs/ and thus be able to make changes to the contributed code.
| |
| | |
| Contributors are encouraged to maintain a branch for each major Moodle release (i.e. 1.8, 1.9, etc.). The HEAD branch should be used as the development branch. Once CVS write access is approved, the maintainer will be able to make whatever changes are needed to maintain the code.
| |
| | |
| That being said, contributors are encouraged to associate each change made to an issue in the tracker. This is accomplished automatically by beginning the CVS commit comment with the issue number. By doing so, the contributor helps to document the reason for the change in the code back to the issue requesting for a change. More information on working with CVS is available at: [[CVS (developer)]].
| |
| | |
| :''Tip:'' Eclipse is an example of an Integrated Development Environment (IDE) that integrates and facilitates many of the common CVS tasks involved in working with Moodle CVS. Instructions for setting up and using Eclipse are available at: [[Eclipse]]. Experienced developers are free to use the tools they are most comfortable/productive with.
| |
| | |
| ==Learning to ''support'' code by providing documentation (https://docs.moodle.org)==
| |
| | |
| Having great code available is wonderful; however, it is important to educate users about how to use the code. Thus, after sharing contributed code it is helpful to provide users with documentation. Documentation pages can be created in [[Main Page|Moodle Docs]] (see the [[MoodleDocs:Guidelines for contributors|guidelines for contributors]]). The documentation page should include a Description of Features, Installation Instructions, Languages Supported, Known Issues, Supported Versions (for Moodle 1.8, 1.9), etc. The page should be categorised as [[:Category:Contributed code|contributed code]] by typing <code><nowiki>[[Category:Contributed code]]</nowiki></code>. This information will let others know how to use the contributed code or how they can become involved in supporting it. Documentation should include for which versions of Moodle the code is designed/intended to work. In addition, it is helpful to indicate for which versions of Moodle support is provided and the degree to which the code is being actively maintained. If a particular version (branch) is not being actively maintained by the contributor/maintainer, then other users may volunteer to help assist in that effort. Information about the maintainer(s) of the code helps users to know to whom they should be grateful.
| |
| | |
| ==Learning to ''share'' code by using the modules and plugins database (http://moodle.org)==
| |
| | |
| Moodle users can easily find information about contributed code in the Modules and Plugins database available at: http://moodle.org/mod/data/view.php?id=6009. To spread the word about the contributed code, the maintainer adds an entry to the Modules and Plugins database providing as much of the information as possible. Having the code in CVS allows for automatically generated nightly zips of the code and simplifies where the code can be found. This helps to avoids having several posts of code in the forums and allows users to efficiently and easily find the latest or most appropriate version of the contributed code. Thus, most contributed code will be found and available at http://download.moodle.org/. Similarly, most documentation should be available at [[Main Page|https://docs.moodle.org]].
| |
| | |
| ==Learning to ''maintain'' code by using the tracker (http://tracker.moodle.org)==
| |
| | |
| 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. Users of the contributed code 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. While it may seem like just one more thing to do, the process of thinking through, creating an issue in the tracker and 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.
| |
| | |
| ==Learning to ''evolve'' code using the moodle.org forums (http://moodle.org)==
| |
| | |
| As users become familiar with the contributed code, discussions about the code are likely to emerge on the Moodle.org site. It is important to respond to users who have questions about how to use the code, suggestions for how to make it better, etc. As the code becomes more popular, it may be helpful to create a specific forum to handle such discussions. If it looks like there is sufficient need for some contributed code to have its own forum, please create a request via the tracker in the MDL-SITE section. 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 contributed code, 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 contributed code into core.
| |
| | |
| ==Goals==
| |
| | |
| 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 CVS, support the code by providing documentation, share code in Modules and Plugins, 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.
| |
| | |
| ==Most common recommendations for contributed code==
| |
| | |
| There are several small issues that the CONTRIB Coordinator will typically check for when reviewing the code prior to committing to the CVS server. These issues help to ensure consistency and quality of code. Any suggestions made by the CONTRIB Coordinator should be considered recommendations aimed to help folks new to the Moodle community collaborate in a way consistent with standard practices within the Moodle community. The suggestions are meant to help avoid potential issues and facilitate the acceptance of your code.
| |
| | |
| # Does the file structure conform to Moodle standards? - Generally speaking, each file should have an appropriate extension (i.e. php, html, css, txt, etc.). To avoid issues with case sensitivity, folders and files are normally lower case; however, there are exceptions to this. Another common recommendation is to place the lang folder within the block or module rather than asking the user to copy files into the main lang folder. Changes made in the get_string function for Moodle 1.9 and onward make it possible to do this which goes a long way in keeping things modular.
| |
| # Does the code work without any obvious errors - The CONTRIB Coordinator will try to install the block or module on a fresh Moodle installation and report back any errors. This testing is done with Debugging set to show All PHP notices and errors (not developer mode). The most common notices have to do with attempting to use a variable that has not been initialized or checked for existence.
| |
| # Does the code use the config_plugins table? - Contributed blocks and modules are encouraged to make use of the config_plugins table rather than the config table. Maintainers are encouraged to read the documentation provided for the get_config and set_config functions in the /lib/moodlelib.php file to help ensure that the footprint for the global $CFG variable does not become bloated.
| |
| # Does the code follow the [[Coding|Coding Guidelines]]? - The CONTRIB Coordinator will look at the code for general readability and point out any obvious deviations from the [[Coding|Coding Guidelines]]. While not all code needs to conform with each and every guideline, maintainers are encouraged to follow those guidelines as closely as possible.
| |
| | |
| ==See also==
| |
| | |
| *[[contrib]] CONTRIB is an area in the Moodle CVS
| |
| *[[Translation]] for information on the translation of contributed code
| |
| *[[Overview]]
| |
| *Using Moodle [http://moodle.org/mod/forum/discuss.php?d=99037 Best practices for code modification?] forum discussion
| |
| | |
| [[Category:Guidelines for contributors]]
| |
