I've read most of the Pro Git book so I now have at least a theoretical understanding of the basics of git. I would like to provide a conceptual framework for myself to help me manage contrib code. This includes testing the code and making it available for others. One thing I would like to see is a solid naming convention for branches, tags, etc. that fits into what is now being done with core. Any and all suggestions, advise, recommendations, questions (including questions I should be asking), etc. would be appreciated. Peace - Anthony
Thank you for opening this discussion Anthony. Even in the core, the particular rules are still getting the final shape and should not be taken as definitive law. However, this is my current understanding of how Moodle contrib space could work in the future (based on several discussions with core guys). Note that CVS contrib will still be available for those who want to use it. Migrating current repository under Git wings is possible (and I recommend it!) and I am happy to help anyone who want to convert their CVS repos into Git as I already have a tuned environment for such conversion.
For Git contrib system, there are two significant differences from the current CVS contrib. The first is that in CVS, we can have single module at the server and that can be checked-out as a whole or just its partial subdirectories. This is because CVS tracks the history of individual files while Git tracks patches against the whole code base. So we can have and manage single contrib divided into separate per-project directories in CVS. This is not possible in Git. For every plugin (mod, block, filter, ...) there must be individual repository.
The second major difference lies in the distribution of the code. With CVS, the contrib module at cvs.moodle.org was the only "official" place for contributed code. This goes against Git nature. Every contributor can decide where they want to publish and maintain their Git repository - maybe their own Git server or some public Git hosting service like Github, Gitorious, repo.or.cz etc. What we need then is a central database that holds the URL of the public Git repository that users can use to obtain their checkout (clone in Gitspeak). See for example my Course contents block record in M&P and check the links to the source code, to the changelog and for the packages.
Given that, I would suggest following:
- The name of the repository should contain "moodle-" prefix to make it clear that it is Moodle related in the list of all repositories at the given host.
- Plugin repositories (that is activity modules, blocks, filters, themes, local plugins etc) should follow the naming policy of plugintype_pluginname (also known as "frankenstyle" - see the docs). So for example a repository with activity module called Foobar should have name moodle-mod_foobar
- There can be as many branches as needed. In Moodle, we use "master" as the main development branch and MOODLE_xx_STABLE for stable branches. I would recommend following this policy in contrib plugins, too.
Hi David,
I have recently submitted a new issue: CONTRIB-2556, as we wanted to share a module. I was following instructions on the wiki - I assume that they are mostly still valid?
Could you please let me know if my understanding is correct:
- Since you've moved to git, moodle.org will simply not host the code for the new contributed code - it can be hosted on github for instance (which is great!)
- We would like to use your tracker to allow people to submit bugs against our module. It means one still needs to raise a ticket like CONTRIB-2556 - to have at least a proper category created in JIRA.
The documentation, forums, modules & plugins database should be used as per Guidelines
cheers,
Tomasz Muras
Enovation Solutions
Yes. I would just recommend to create an appropriate directory in CVS contrib anyway so that you "reserve" the name of your plugin. That directory in CVS contrib can contain just a single file with the information about the Git repository location. Alternatively, you can consider publishing snapshots of the plugin in CVS contrib so that administrators who use CVS and not Git can install your plugin from there.
David "Alternatively, you can consider publishing snapshots of the plugin in CVS contrib..."
How does one do that?
Joseph
we do that for the face to face module (sometimes not as often as we should!) - it's just a manual process - taking a copy of the latest code from git (static files) and then uploading those files to CVS.
Davin, Anthony
I'm writing here instead of adding comment in CONTRIB-2556 so it may help others that browse that forum.
Are you suggesting to track contrib bugs on github? I don't really mind but I think it would be easier for end users to let them use only one ticketing system (e.g. Moodle's one). I will go with whatever your preference is.
Tomasz Muras
Enovation Solutions
Definitely not. The CONTRIB project at tracker.moodle.org should be used for issue tracking.
The suggestion is to move your code from cvs.moodle.org to any public git hosting that you like - with github being one popular choice.
Tomasz - My apologies for any confusion, the Moodle tracker is the preferred place for filing bugs precisely because, as you note, it gives end users a consistent experience. Peace - Anthony
The question regarding issue tracking seems to be answered by this thread. But what about documentation for contributed modules?
Should this go to:
* Moodle plug-in database
* Moodle Docs
* GitHub
If the code resides on GitHub also maintaining the documentation there seems convenient and logical. However, it would move the documentation away from Moodle's own systems. Any thoughts?
Frank
Should this go to:
* Moodle plug-in database
* Moodle Docs
* GitHub
If the code resides on GitHub also maintaining the documentation there seems convenient and logical. However, it would move the documentation away from Moodle's own systems. Any thoughts?
Frank
Personally, I think that the Plugins system having a field that links to the docs should be enough - then they can live where the maintainer chooses.
I prefer to use a system which generates my documentation as HTML pages - this doesn't fit with the Moodle Docs wiki very well. However this does fit very nicely with GitHub (you can have a seperate branch of your repo where you can put web pages which are then accessible through a GitHub.com URL).
Hi, Frank.
Beyond help strings, the best place for documentation is in the Docs. When a user is using a module (contributed or not), they are linked to the docs for further information. On configuration pages there are links to the docs and contributing authors should ensure that they write pages where these links lead to.
We now have two Docs wikis: the User docs and the Dev docs. Links in Moodle point to the User docs, and you should, at least, have some documentation on how to use your module there. The dev docs can be used as a place where you plan the development, if you need space to do that.
Michael;
Hi, Michael,
Thanks for the hint. That seems indeed to be best solution to prevent scattering the documentation across several places
Cheers,
Frank
Thanks for the hint. That seems indeed to be best solution to prevent scattering the documentation across several places
Cheers,
Frank
I thought some examples might help with David's explanation, so here are some examples of people getting it right:
Dear Tim et al,
I've started moving to Git, but before I get to far, can I confirm that the repository name is correct -> https://github.com/gjb2048/moodle-courseformat_topcoll - I know you told me on iMoot but lost the info! And as with lots of things in life the complex is easy and the simple things can sometimes be the hardest!
Thanks,
Gareth
Not quite. With a course fromat, you would use get_string('strname', 'format_topcoll'); so the repository name should be https://github.com/gjb2048/moodle-format_topcoll.
Difinitive list of prefixes by plugin type here: http://docs.moodle.org/dev/Frankenstyle. (Well, acutally the real difinitive list is print_object(get_plugin_types())). Note that for modules, you need to add mod_, even though you don't need that in get_string.
Tim,
Superb, thank you .
Gareth
Just looking at those, while planning moving the sloodle code over to Git.
(See our discussion here):
http://www.sloodle.org/moodle/mod/forum/discuss.php?d=3474
We have four things that get added to Moodle in a complete sloodle install: an activity module, two blocks and an assignment type. These have a common dependency on the activity module version. Looking at the way skodak and mudrd8mz have done it I guess they should all be separate repos. That instinctively feels wrong, but maybe I've spent too long with SVN?
I did separate repos with https://github.com/timhunt/moodle-qtype_opaque and https://github.com/timhunt/moodle-qbehaviour_opaque which require each other to work.
If you look at the readme there, you can see it works fine to clone a plugin into a subfolder of a main git checkout, so doing development like this is not a problem.
OK, that makes sense - I guess I can cobble something together with sub-modules if having the thing split into 4 repos hurts.
Hi,
thanks for the discussion. I was looking for a perfect workflow to develop contrib modules. I think the solution is described at: http://progit.org/book/ch6-6.html (git submodules)
Best regards,
David