Development:Guidelines for contributed code - Revision history

Aborrow at 22:20, 28 January 2011

2011-01-28T22:20:10Z

← Older revision		Revision as of 22:20, 28 January 2011
Line 1:		Line 1:
	This page describes the various ways to share and work collaboratively on contributed code.		This page describes the various ways to share and work collaboratively on contributed code. In the past, Moodle CONTRIB code was often stored on the Moodle CVS server. As Moodle code transitions to [https://docs.moodle.org/en/Git Git], CONTRIB code will also be transitioning with a goal of having all code maintained via git repositories by August 2011. Don't worry if you have code on CVS and do not know Git as there are many people willing to help you with the transition especially [https://docs.moodle.org/en/User:Anthony_Borrow Anthony Borrow].
	~~#Submit~~ code in the ~~[http://tracker.moodle~~.~~org/~~ Moodle ~~Tracker] under~~ [~~http~~://~~tracker~~.moodle.org/~~browse~~/CONTRIB ~~CONTRIB].~~
	~~#Work~~ with ~~submitted~~ code ~~in [http://cvs~~.~~moodle.org Moodle~~'s CVS ~~server]~~
	~~#Document features~~ and ~~install instructions in~~ [https://docs.moodle.org ~~Moodle Docs]~~
	~~#Share and distribute code in the [http://moodle.org/mod~~/~~data~~/~~view.php?id=6009 Modules and Plugins database]~~
	~~#Talk and support code in the [http~~:~~//moodle.org/course/view.php?id=5 Using Moodle forums~~]
	~~#Maintain and further develop code with the [http://tracker~~.~~moodle.org Moodle Tracker]~~

	==The Frequently ~~asked question~~==		For those neither familiar with CVS nor Git, it is recommended that you [https://docs.moodle.org/en/Git#Books_and_tutorials learn Git basics]. The nice thing about using Git is that it will leave control of the code in the hands of contributor.

			*'''Sharing code''' - Contributed code will be shared and maintained using a public Git repository (i.e. github.com, gitorious.org, etc.).
			*'''Reviewing code''' - If you would like your code to be tested and reviewed, please create an issue in the [http://tracker.moodle.org/ Moodle Tracker] under [http://tracker.moodle.org/browse/CONTRIB CONTRIB].
			*'''Documenting code''' - You can maintain helpful documentation of the features and installation instructions in [https://docs.moodle.org Moodle Docs]
			*'''Distributing code''' - You can help others find your code by adding an entry to the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database]
			*'''Discussing the code''' - You can discuss the functionality and answer questions about how to use your code in the [http://moodle.org/course/view.php?id=5 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 [http://tracker.moodle.org/ Moodle Tracker].
			*'''Maintaining code''' - You can further develop your code by fixing issues, adding features, and responding to other issues with the [http://tracker.moodle.org/ 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 contributed 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 contributed code. Those issues will automatically be assigned to the component lead/primary maintainer.

			==The CONTRIB Frequently Asked Question (FAQ)==
	'''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?		'''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.		'''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 [https://docs.moodle.org/en/Pedagogy 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 contributed code.

	==How to submit 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~~].		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 [http://github.com/ github.com] and [http://gitorious.org/ 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).

	~~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~~.		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.

	*Contributors are encouraged to ~~follow Moodle's coding guidelines [[Development:Coding]].~~		==How to request that your code be tested/reviewed==
	*A list of current tracker [http:/~~/tracker.moodle.org/secure/BrowseProject.jspa contributed projects is here].~~

	~~==How to work with code in CVS==~~		#If you do not already have an account on the [http://tracker.moodle.org] Moodle Tracker], create one and login.
	~~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.~~		#Create a new "Task" issue in the "Non-core contributed modules" project. 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

	~~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.		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.

	~~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)~~]].		*Contributors are encouraged to follow Moodle's coding guidelines [[Development:Coding]].

	~~:''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~~.		*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.

	~~: Another IDE~~ with ~~CVS support is [[Development:Setting_up_Netbeans\|NetBeans]]~~.		*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==		==How to provide documentation==
Line 58:		Line 65:
	==Share code with modules and plugins database==		==Share code with modules and plugins database==
	Now you have a place for users to get your code, how will they know it exists? Moodle users can easily find information about contributed code in the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database]. When you add an entry to this database, remember that it is searchable by any field. Every field is not required, but providing as much information as possible will help people who would like to find, read about, and then install your contribution. In particular, the name of the module and the description of its function are important. Screen shots are helpful (but please, not larger than 350px wide!). Links to discussion (on Moodle.org or other forum) and documentation (link to your page in the [https://docs.moodle.org Moodle docs] or another location) should be included if possible.		Now you have a place for users to get your code, how will they know it exists? Moodle users can easily find information about contributed code in the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database]. When you add an entry to this database, remember that it is searchable by any field. Every field is not required, but providing as much information as possible will help people who would like to find, read about, and then install your contribution. In particular, the name of the module and the description of its function are important. Screen shots are helpful (but please, not larger than 350px wide!). Links to discussion (on Moodle.org or other forum) and documentation (link to your page in the [https://docs.moodle.org Moodle docs] or another location) should be included if possible.

	If you are maintaining your code using Moodle's CVS server, a zip file of your code is automatically created and stored on Moodle's download server ([http://download.moodle.org/ http://download.moodle.org]). Therefore, the download link for most contributed code will be a link to [http://download.moodle.org/ Moodle's download server]. If you host your code on a site other than [http://download.moodle.org/ Moodle's download server], please ensure that the download link goes directly to the file and that the file is in a standard archive format (i.e. preferably a zip file). This makes it easier for users to locate the file quickly and helps to standardize installation of the code.

	By way of example, if you have a CONTRIB plugin block called birthday, the preferred download link would be http://download.moodle.org/download.php/plugins/blocks/birthday.zip for the HEAD branch. For the MOODLE_19_STABLE branch, the URL would be http://download.moodle.org/download.php/plugins19/blocks/birthday.zip. Please note that the download.php is important as that is used to help produce the [http://download.moodle.org/stats.php download stats].

	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. The comments are not emailed automatically.		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. The comments are not emailed automatically.

Rcollman: /* Possible format for a contributed code Moodle Docs page */

2010-11-29T13:32:13Z

Possible format for a contributed code Moodle Docs page

← Older revision		Revision as of 13:32, 29 November 2010
Line 54:		Line 54:

	When no thread or forum exists for discussion, put a link to the Contributed Code forum.		When no thread or forum exists for discussion, put a link to the Contributed Code forum.
	*Discussions: Please create or find a discussion topic in the [http://moodle.org/mod/forum/view.php?id=44 Contributed Code forum]		*Discussions: Please create or find a discussion topic in the <nowiki>[http://moodle.org/mod/forum/view.php?id=44 Contributed Code forum]</nowiki>

	==Share code with modules and plugins database==		==Share code with modules and plugins database==

Rcollman: /* How to provide documentation */ Suggestion

2010-11-29T13:31:31Z

How to provide documentation: Suggestion

← Older revision		Revision as of 13:31, 29 November 2010
Line 37:		Line 37:

	Other information might include: Languages Supported, Known Issues, Supported Versions (for Moodle 1.8, 1.9), and maybe which are being actively supported. The page should be added to the contributed code category by typing <code><nowiki>[[Category:Contributed code]]</nowiki></code> at the bottom of the page.		Other information might include: Languages Supported, Known Issues, Supported Versions (for Moodle 1.8, 1.9), and maybe which are being actively supported. The page should be added to the contributed code category by typing <code><nowiki>[[Category:Contributed code]]</nowiki></code> at the bottom of the page.

			===Possible format for a contributed code Moodle Docs page===
			You can copy and paste the below into your Moodle documentation page. Please add the URL links. '''This is only a suggestion'''.
			Start with a 2-4 line introduction. The Plug In Name works with the activity module.
			It makes the life of the teacher easier by ...
			==Features==
			* Add features list or overview description here <nowiki><br></nowiki>
			<nowiki> [[Image:Sample_screen_shot\|thumb\|500px\|center\|Title of screenshot]]</nowiki>
			==Installation==
			Place install instructions here
			==Tips and tricks==
			*Optional section, usually added by users later
			==See also==
			*[Place http_address_for_M&P_entry_here Name of Entry here] is a Modules and plugins database page that has download links and more information.
			*Discussions: [Place http_address_for_moodle_forum_or_thread_here Name of forum]

			When no thread or forum exists for discussion, put a link to the Contributed Code forum.
			*Discussions: Please create or find a discussion topic in the [http://moodle.org/mod/forum/view.php?id=44 Contributed Code forum]

	==Share code with modules and plugins database==		==Share code with modules and plugins database==

Aborrow: /* Does the file structure conform to Moodle standards? */

2010-06-30T23:48:20Z

Does the file structure conform to Moodle standards?

← Older revision		Revision as of 23:48, 30 June 2010
Line 79:		Line 79:

	=== Does the file structure conform to Moodle standards? ===		=== 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. Similarly, to respect the modular nature of Moodle if a block requires a library it is usually preferred to keep it as a subdirectory in the block's folder.		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. Similarly, to respect the modular nature of Moodle if a block requires a library it is usually preferred to keep it as a subdirectory in the block's folder. This can be especially helpful if your code is dependent upon a particular version of an external library.

	=== Does the code work without any obvious errors? ===		=== Does the code work without any obvious errors? ===

Aborrow: /* Does the file structure conform to Moodle standards? */

2010-06-30T23:42:40Z

Does the file structure conform to Moodle standards?

← Older revision		Revision as of 23:42, 30 June 2010
Line 79:		Line 79:

	=== Does the file structure conform to Moodle standards? ===		=== 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.		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. Similarly, to respect the modular nature of Moodle if a block requires a library it is usually preferred to keep it as a subdirectory in the block's folder.

	=== Does the code work without any obvious errors? ===		=== Does the code work without any obvious errors? ===

Tsala: /* See also */ Development:Migrating contrib code to 2.0

2010-05-01T07:55:50Z

← Older revision		Revision as of 07:55, 1 May 2010
Line 93:		Line 93:
	==See also==		==See also==

			*[[Development:Migrating contrib code to 2.0]]
	*[[Development:contrib]] CONTRIB is an area in the Moodle CVS		*[[Development:contrib]] CONTRIB is an area in the Moodle CVS
	*[[Translation]] for information on the translation of contributed code		*[[Translation]] for information on the translation of contributed code

Aborrow: /* Share code with modules and plugins database */

2010-03-03T16:57:54Z

Share code with modules and plugins database

← Older revision		Revision as of 16:57, 3 March 2010
Line 43:		Line 43:
	If you are maintaining your code using Moodle's CVS server, a zip file of your code is automatically created and stored on Moodle's download server ([http://download.moodle.org/ http://download.moodle.org]). Therefore, the download link for most contributed code will be a link to [http://download.moodle.org/ Moodle's download server]. If you host your code on a site other than [http://download.moodle.org/ Moodle's download server], please ensure that the download link goes directly to the file and that the file is in a standard archive format (i.e. preferably a zip file). This makes it easier for users to locate the file quickly and helps to standardize installation of the code.		If you are maintaining your code using Moodle's CVS server, a zip file of your code is automatically created and stored on Moodle's download server ([http://download.moodle.org/ http://download.moodle.org]). Therefore, the download link for most contributed code will be a link to [http://download.moodle.org/ Moodle's download server]. If you host your code on a site other than [http://download.moodle.org/ Moodle's download server], please ensure that the download link goes directly to the file and that the file is in a standard archive format (i.e. preferably a zip file). This makes it easier for users to locate the file quickly and helps to standardize installation of the code.

	By way of example, if you have a CONTRIB plugin block called birthday, the preferred download link would be http://download.moodle.org/download.php/plugins/~~block~~/birthday.zip for the HEAD branch. For the MOODLE_19_STABLE branch, the URL would be http://download.moodle.org/download.php/plugins19/~~block~~/birthday.zip. Please note that the download.php is important as that is used to help produce the [http://download.moodle.org/stats.php download stats].		By way of example, if you have a CONTRIB plugin block called birthday, the preferred download link would be http://download.moodle.org/download.php/plugins/blocks/birthday.zip for the HEAD branch. For the MOODLE_19_STABLE branch, the URL would be http://download.moodle.org/download.php/plugins19/blocks/birthday.zip. Please note that the download.php is important as that is used to help produce the [http://download.moodle.org/stats.php download stats].

	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. The comments are not emailed automatically.		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. The comments are not emailed automatically.

Aborrow at 16:56, 3 March 2010

2010-03-03T16:56:38Z

← Older revision		Revision as of 16:56, 3 March 2010
Line 42:		Line 42:

	If you are maintaining your code using Moodle's CVS server, a zip file of your code is automatically created and stored on Moodle's download server ([http://download.moodle.org/ http://download.moodle.org]). Therefore, the download link for most contributed code will be a link to [http://download.moodle.org/ Moodle's download server]. If you host your code on a site other than [http://download.moodle.org/ Moodle's download server], please ensure that the download link goes directly to the file and that the file is in a standard archive format (i.e. preferably a zip file). This makes it easier for users to locate the file quickly and helps to standardize installation of the code.		If you are maintaining your code using Moodle's CVS server, a zip file of your code is automatically created and stored on Moodle's download server ([http://download.moodle.org/ http://download.moodle.org]). Therefore, the download link for most contributed code will be a link to [http://download.moodle.org/ Moodle's download server]. If you host your code on a site other than [http://download.moodle.org/ Moodle's download server], please ensure that the download link goes directly to the file and that the file is in a standard archive format (i.e. preferably a zip file). This makes it easier for users to locate the file quickly and helps to standardize installation of the code.

			By way of example, if you have a CONTRIB plugin block called birthday, the preferred download link would be http://download.moodle.org/download.php/plugins/block/birthday.zip for the HEAD branch. For the MOODLE_19_STABLE branch, the URL would be http://download.moodle.org/download.php/plugins19/block/birthday.zip. Please note that the download.php is important as that is used to help produce the [http://download.moodle.org/stats.php download stats].

	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. The comments are not emailed automatically.		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. The comments are not emailed automatically.

Tsala: /* How to provide documentation */ small rewording

2009-07-04T09:35:26Z

How to provide documentation: small rewording

← Older revision		Revision as of 09:35, 4 July 2009
Line 36:		Line 36:
	A documentation page for a contributed module should have some basic elements. A brief introduction of what the code does, a "Features" heading, perhaps a "Installation", "Tips and tricks" and "See also" headings, all with content of course. Sometimes a screenshot is worth 1000 words. In the "See also" put a link to the Modules and Plug database, with a note that this is the place to download versions, and the forum where questions can be answered at moodle.org.		A documentation page for a contributed module should have some basic elements. A brief introduction of what the code does, a "Features" heading, perhaps a "Installation", "Tips and tricks" and "See also" headings, all with content of course. Sometimes a screenshot is worth 1000 words. In the "See also" put a link to the Modules and Plug database, with a note that this is the place to download versions, and the forum where questions can be answered at moodle.org.

	Other information might include: Languages Supported, Known Issues, Supported Versions (for Moodle 1.8, 1.9), and maybe which are being actively supported. ~~We suggest placing~~ <code><nowiki>[[Category:Contributed code]]</nowiki></code> at the bottom of the page.		Other information might include: Languages Supported, Known Issues, Supported Versions (for Moodle 1.8, 1.9), and maybe which are being actively supported. The page should be added to the contributed code category by typing <code><nowiki>[[Category:Contributed code]]</nowiki></code> at the bottom of the page.

	==Share code with modules and plugins database==		==Share code with modules and plugins database==

Nakohdo: /* Does the code use the config_plugins table? */

2009-03-29T10:11:05Z

Does the code use the config_plugins table?

← Older revision		Revision as of 10:11, 29 March 2009
Line 82:		Line 82:
	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.		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? ===		=== 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 [http://xref.moodle.org/lib/moodlelib.php.html#get_config get_config()] and [http://xref.moodle.org/lib/moodlelib.php.html#set_config set_config()]] functions in the /lib/moodlelib.php file to help ensure that the footprint for the global $CFG variable does not become bloated.
			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 [http://xref.moodle.org/lib/moodlelib.php.html#get_config get_config()] and [http://xref.moodle.org/lib/moodlelib.php.html#set_config 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]]? ===		=== Does the code follow the [[Coding\|Coding Guidelines]]? ===