Hi,
I was thinking it would be useful to have a template directory with all the "boiler-plate" for a Geany plugin under version control to get people started quicker writing a new plugin that could become part of the Geany Plugins project easier. I saw something similar[1] in the GStreamer project.
My ideas was to put in the directory the files required for the build system(s), a generic README template, a GPL2 COPYING, etc, and a src/ dir with a basic demo plugin (maybe from the Geany plugins/ dir?).
What other common files besides these should be in there? AUTHORS COPYING ChangeLog Makefile.am NEWS README THANKS TODO wscript_build wscript_configure (are both these Waf files needed?) ../build/foo.m4 (how to include if it's in .. ?) src/foo.c src/Makefile.am configure.ac? (for building before it's in Geany Plugins proper)
What do you guys think? Is it worthwhile? Have I missed any important files?
I was going to follow this up with a tutorial on the Wiki explaining how to check-out the template, describe which files needed to be modified and how to do so, etc. Also it would have some more general notes from HACKING, getting commit access, the cppcheck stuff and so on. This would be a good companion to the plugin howto I think.
I was also thinking about doing a similar template/tutorial for a Vala plugin.
Feedback would be appreciated.
Cheers, Matthew Brush
[1] http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/chapter-bu...
Le 03/05/2011 03:54, Matthew Brush a écrit :
Hi,
I was thinking it would be useful to have a template directory with all the "boiler-plate" for a Geany plugin under version control to get people started quicker writing a new plugin that could become part of the Geany Plugins project easier. I saw something similar[1] in the GStreamer project.
My ideas was to put in the directory the files required for the build system(s), a generic README template, a GPL2 COPYING, etc, and a src/ dir with a basic demo plugin (maybe from the Geany plugins/ dir?).
What other common files besides these should be in there? AUTHORS COPYING ChangeLog Makefile.am NEWS README THANKS TODO wscript_build wscript_configure (are both these Waf files needed?) ../build/foo.m4 (how to include if it's in .. ?) src/foo.c src/Makefile.am configure.ac? (for building before it's in Geany Plugins proper)
What do you guys think? Is it worthwhile? Have I missed any important files?
I was going to follow this up with a tutorial on the Wiki explaining how to check-out the template, describe which files needed to be modified and how to do so, etc. Also it would have some more general notes from HACKING, getting commit access, the cppcheck stuff and so on. This would be a good companion to the plugin howto I think.
I don't think the template is really useful, apart maybe for Makefile.ams and wscript_* (though I don't know exactly what's in the later), but I think that for the other files a tutorial is just enough and probably even better:
* AUTHORS just contains he author's name, nothing predictable * COPYING OK, should probably be a GPL, but we already have both v2 and v3 (maybe we should fix this BTW...) * ChangeLog, maybe required for the build system, not sure, but anyway its content is not predictable either * NEWS again, not predictable * README same * THANKS, again * TODO same, and not even needed * ../build/foo.m4 though it's quite similar from a plugin to another should not be put in the real build dir, so where to place it? I think a tutorial explaining what to put in it is better * src/foo.c though a small part of it will be the same for every plugin, most of it's content will not be the same, and we even already have a doc/demo for this * configure.ac is a bit pointless since we talk about geany-plugins integration ^^
So I think the tutorial is a great idea, but I'm not sure the demo entry is.
Cheers, Colomban
What do you guys think? Is it worthwhile? Have I missed any important files?
I think in principle anything that reduces the barriers to creating plugins is worthwhile. We should never forget that what may be second nature to experienced open source developers may be a confusing "blocker" to an inexperienced developer or even an experienced developer who has only used Windows before.
I was going to follow this up with a tutorial on the Wiki explaining how to check-out the template, describe which files needed to be modified and how to do so, etc. Also it would have some more general notes from HACKING, getting commit access, the cppcheck stuff and so on. This would be a good companion to the plugin howto I think.
Yes, a tutorial would be a good idea. I'm happy to help review it.
I don't think the template is really useful, apart maybe for Makefile.ams and wscript_* (though I don't know exactly what's in the later), but I think that for the other files a tutorial is just enough and probably even better:
* AUTHORS just contains he author's name, nothing predictable
Just an example layout and a note not to forget regular contributors
* COPYING OK, should probably be a GPL, but we already have both v2 and v3 (maybe we should fix this BTW...)
Whats to fix, Geany is released under GPL v2 or later so plugins must have a compatible license. But that includes GPLv3, modified BSD and lots more see
http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses
No point in changing things/adding restrictions we don't need to and we can't just go change licenses without the owners permission.
And if Geany itself upgraded to V3 then all plugins that use V2 would be technically illegal since v3 is not backward compatible and lots of people still don't agree with v3.
* ChangeLog, maybe required for the build system, not sure, but anyway its content is not predictable either
No, but an example of good practice won't hurt.
* NEWS again, not predictable * README same
Examples of things to put in it could be worthwhile, how to build, basic use/pointer to the copious documentation, restrictions, configuration, bugs etc.
* THANKS, again * TODO same, and not even needed
Just say this is where you put known problems, known upgrades, etc
* ../build/foo.m4 though it's quite similar from a plugin to another should not be put in the real build dir, so where to place it? I think a tutorial explaining what to put in it is better
Arrrgggg, I'm allergic to m4
* src/foo.c though a small part of it will be the same for every plugin, most of it's content will not be the same, and we even already have a doc/demo for this
Well probably use the demo here, two birds with one stone etc.
* configure.ac is a bit pointless since we talk about geany-plugins integration ^^
So I think the tutorial is a great idea, but I'm not sure the demo entry is.
Definitely agree that expanded tutorial is worthwhile, butthink there is value in the template too, and can incorporate the example.
Cheers Lex
Cheers, Colomban _______________________________________________ Geany-devel mailing list Geany-devel@uvena.de https://lists.uvena.de/cgi-bin/mailman/listinfo/geany-devel
On 05/03/11 05:42, Colomban Wendling wrote:
I don't think the template is really useful, apart maybe for Makefile.ams and wscript_* (though I don't know exactly what's in the later), but I think that for the other files a tutorial is just enough and probably even better:
Maybe I used the wrong word or you misunderstood what I mean by template, I don't mean "download this and your good to go", I mean "download this, edit the boilerplate files as per the comments/examples in them (and described in a tutorial), and you've got a good start".
- AUTHORS just contains he author's name, nothing predictable
I predict this file will contain information about the author(s), for example:
Your Name youremail@email.org
Then the new developer knows she needs to replace the above with real information.
- COPYING OK, should probably be a GPL, but we already have both v2 and
v3 (maybe we should fix this BTW...)
Probably a safe bet to include GPLv2 in the template, IMO. Unless there is a license conflict, I don't see a point in not letting the developer choose her license.
- ChangeLog, maybe required for the build system, not sure, but anyway
its content is not predictable either
I predict this file will log the changes made the plugins source code, for example:
1970-01-01 Your Name youremail@email.org
* Start counting in seconds until the end of the world (Jan 19, 2038).
Pretty obvious to new developer what to do with this file.
- NEWS again, not predictable
I predict this one to contain news about the latest release (or a reference to see the ChangeLog), for example:
Your Plugin 0.01 (January 1, 1970)
* First official release
Then the new developers knows what her ChangeLog should look like and it's pretty obvious how to use it.
- README same
I predict this one to contain documentation on how to use the plugin. I was thinking for this to make a generic template in restructedtext with the sections most commonly used in other geany-plugins (since they are mostly the same) and some generic text for the new developer to replace with real documentation.
- THANKS, again
- TODO same, and not even needed
Same as above predictions but for these files. Like I said at the top, I think you misunderstood what I meant by template.
- ../build/foo.m4 though it's quite similar from a plugin to another
should not be put in the real build dir, so where to place it? I think a tutorial explaining what to put in it is better
I would probably place it under an examples/ dir or similar and inside it would be commented to explain how to use the file (as with the other files) so a new developer knows she has to add dependencies there, etc.
- src/foo.c though a small part of it will be the same for every
plugin, most of it's content will not be the same, and we even already have a doc/demo for this
Probably just reuse plugins/demoplugin.c for this (or an updated version used in the tutorial).
- configure.ac is a bit pointless since we talk about geany-plugins
integration ^^
Not pointless if you want to build your plugin inside the checked-out directory, as would be described in the tutorial (before being added to the geany-plugins project).
So I think the tutorial is a great idea, but I'm not sure the demo entry is.
*Template*
Thanks for your feedback.
Cheers, Matthew Brush
Le 04/05/2011 02:20, Matthew Brush a écrit :
On 05/03/11 05:42, Colomban Wendling wrote:
I don't think the template is really useful, apart maybe for Makefile.ams and wscript_* (though I don't know exactly what's in the later), but I think that for the other files a tutorial is just enough and probably even better:
Maybe I used the wrong word or you misunderstood what I mean by template, I don't mean "download this and your good to go", I mean "download this, edit the boilerplate files as per the comments/examples in them (and described in a tutorial), and you've got a good start".
[...]
Still not really convinced that it's really useful, but you seem to know why you think it is regarding how you defend it :D And I won't prevent anyone from adding this, why not if it has users.
- configure.ac is a bit pointless since we talk about geany-plugins
integration ^^
Not pointless if you want to build your plugin inside the checked-out directory, as would be described in the tutorial (before being added >
to the geany-plugins project).
Hum, the thing is that for a "newbie" configure.ac generally looks like dark magic or at least weird stuff, so you'll need to explain how it works and what to modify, but it won't be valid for real G-P plugin, because the G-P's configure.ac has a quite sophisticated layout. Or you would copy & paste the G-P specific M4 macros? (GP_*)
Cheers, Colomban
Am 03.05.2011 03:54, schrieb Matthew Brush:
Hi,
I was thinking it would be useful to have a template directory with all the "boiler-plate" for a Geany plugin under version control to get people started quicker writing a new plugin that could become part of the Geany Plugins project easier. I saw something similar[1] in the GStreamer project.
My ideas was to put in the directory the files required for the build system(s), a generic README template, a GPL2 COPYING, etc, and a src/ dir with a basic demo plugin (maybe from the Geany plugins/ dir?).
What other common files besides these should be in there? AUTHORS COPYING ChangeLog Makefile.am NEWS README THANKS TODO wscript_build wscript_configure (are both these Waf files needed?) ../build/foo.m4 (how to include if it's in .. ?) src/foo.c src/Makefile.am configure.ac? (for building before it's in Geany Plugins proper)
What do you guys think? Is it worthwhile? Have I missed any important files?
I was going to follow this up with a tutorial on the Wiki explaining how to check-out the template, describe which files needed to be modified and how to do so, etc. Also it would have some more general notes from HACKING, getting commit access, the cppcheck stuff and so on. This would be a good companion to the plugin howto I think.
I was also thinking about doing a similar template/tutorial for a Vala plugin.
Feedback would be appreciated.
I like this idea, but really think it would fit better inside upcoming wiki.
Cheers, Frank