Re: [Debian-sf-devel] Plugins thingy, draft #2

[Christian Bayle]

Hi some comments/ideas take the good throw the bad :)

Roland Mas wrote:

>  Hi again,
>
> Here's the state of the README.Plugins I've written so far.  Places
> marked [TODO] are, well, places where it is known that further
> thinking is needed.  Places where implementation is needed are also
> marked.  I'll try to implement at least some of the less controversial
> stuff this weekend, and post it for review before committing anything
> to CVS.
>
>  Comments and thoughts and ideas for how to implement missing stuff
> are welcome and looked for :-)
>
> Roland.
>  
>
> ------------------------------------------------------------------------
>
> DEBIAN SOURCEFORGE PLUGINS HOWTO
> --------------------------------
>
> Here is a short HOWTO explaining how plugins work in Debian
> Sourceforge, and how to make a new one.
>
> ,-----------------------------------------------------------------------.
> |  This is a DRAFT document!  The plugin system is not implemented yet, |
> | and not completely designed either.  Please read carefully, think     |
> | about it, and submit comments and fixes.                              |
> `-----------------------------------------------------------------------'
>
>  It was written by Roland Mas <address@hidden>.
>
> WHAT PLUGINS ARE, AND WHY THEY ARE USEFUL
> -----------------------------------------
>
>  Plugins are extensions to the "core" of Sourceforge, providing extra
> functionality without being tightly integrated within Sourceforge
> proper.  They are useful because they allow for independent
> development of third-party functionality, and they add flexibility to
> Sourceforge as to what features are available on a particular
> installation.
>
>  As an example, it's been suggested to integrate a shared calendar
> application in Sourceforge.  It's a good idea and an interesting
> feature, but not one that everybody wants.  Thus, including it in the
> Sourceforge code would piss off someone.  Additionnally, there might
> be several competing implementations for such a calnedar application.
> Choosing one among them would also piss off people.  So it is made
> possible to have a system so that different implementations can exist
> and be installed separately.
>
> HOW PLUGINS WORK
> ----------------
>
>  It is expected that a plugin is just some new feature added to
> Sourceforge, and not a change in the behaviour of existing features.
> A plug-in should therefore only add files, not change existing ones.
> Whether these files be web pages, offline scripts, static
> documentation or else is not relevant.
>
>  Of course, *some* changes will have to be made to the "core" files,
> if only to add links to new web pages, for instance.  These changes
> are acceptable, and will be discussed below.  Here come the details
> about how the plugin system is implemented.
>
> - A plugin will be identified primarily by a string handle, which will
> be static across all installations of this plugin.  It should be
> composed of lowercase letters only, because it's going to be used in
> table names and we don't want namespace conflicts.  For instance, if
> the ACME company writes a time tracking tool plugin, the handle for
> that plugin could be "acmetimetracker".  When installed, the plugin
> will be assigned an integer identifier.  This id might vary from site
> to site, and should not be depended upon.
>
>  We [the Sourceforge-proper maintainers team] will maintain some sort
> of list of allocated plugin names so that different plugins get
> different allocated identifiers.
>
> - Tables in the database schema: special tables have been added to the
> database schema to keep track of installed plugins.  They are
> described below (simplified descriptions):
> ,----
> | CREATE TABLE plugins (plugin_id integer,
> |                       plugin_name character(32),
> |                       plugin_desc text,
> |                       CONSTRAINT plugins_pkey PRIMARY KEY (plugin_id)
> |                      )
> | CREATE TABLE group_plugin (group_plugin_id integer,
> |                            group_id integer,
> |                            plugin_id integer,
> |                            CONSTRAINT PRIMARY KEY (plugin_id),
> |                            CONSTRAINT FOREIGN KEY (group_id) REFERENCES 
> groups(group_id)
> |                           )
> | CREATE TABLE user_plugin (user_plugin_id integer,
> |                           user_id integer,
> |                           plugin_id integer,
> |                           CONSTRAINT PRIMARY KEY (plugin_id),
> |                           CONSTRAINT FOREIGN KEY (user_id) REFERENCES 
> users(user_id)
> |                          )
> `----
>
>  "plugins" lists the installed plugins, with the numeric id, the
> string handle (say, "acmetimetracker") and a description.
>
>  "group_plugin" is a way to store the fact that a group "uses" a
> plugin without needing to add a "uses_acmetimetracker" to the groups
> table for each known plugin.
>
>  "user_plugin" is the same, for users.
>
> - A plugin may create its own tables in the same database.  These
> tables must be named plugin_foo_* if the plugin's string identifier is
> "foo".  One suggested table is plugin_foo_meta_data, which should be
> used to store the plugin meta-data, such as the installed version.
> The plugin can then use some code like db-upgrade.pl if its database
> schema changes over time.
I would prefer that  there is only one table containing versionning 
information.
The actual debian_meta_data  table is enough to store informations you 
plan for
plugins table if you add desc field. Nevertheless I would add a version 
field to plugins table
I'm not sure that id and name are both necessary, except if you want to 
allow to change plugin name.

> [TODO: Standardise the command/script/something below]
>  These tables may have foreign key referential integrity constraints
> going from them to standard tables, but not the other way round.  If
> they have, then a command/script/something must be provided so that
> the main db-upgrade.pl can disable the constraints and re-enable them
> afterwards in case some database schema changes are needed.
>
>  Similarly, a plugin may create sequences, indexes, views, etc,
> provided that their names are prefixed with plugin_foo_ too.
>
>  A plugin should not modify the data in tables that do not belong to
> it.  If it really needs to, then please discuss it with us first,
> there might be cases where it's needed/useful.  Reading those data is
> okay, but it must be careful not to leak any info to places/users
> which normally wouldn't have had access to it.
>  
There are some case where it can be interesting to use standart table 
like for this case:
-If you want to add different documentation field to Project it's better 
to use the documentation
table.
-If you want to add extra info to the user table like phone number, 
adress, can be interesting to
do this some kind of construction made in survey
I would say that in many case it could be use some kind of thing like it 
was done for tracker that allow
to manage, patch, bug, support....

> - Functions in Group.class and User.class: the Group and User classes
> now have a usesPlugin() method.  It takes a single parameter, the
> "acmetimetracker" identifier for the module, and returns a boolean if
> the particular user/group has turned on the use of that module.
>  
Maybe we could also adopt the overload facility used in theme to be able 
to overload some already existing functions.
just for  memory
There is a Layout.class table  that contains standart function for sf layout
There are many Theme.class that can decide to reimplement or not done 
for this Layout function

> - A plugin should not change the existing files, except insofar as it
> adds links to its own web pages.  Of course, these additions will have
> to be merged into the pages of the main package, but it should be just
> a matter of inserting lines like
> ,----
> | if $this_group->usesPlugin("foo") {
> |    echo [Link to /plugins/foo/index.php?parameters]
> | }
> `----
> in the existing pages.  Most plugins will probably only add these
> links on the project summary page and/or on the user personal pages.
>  
If you add some graphic elements this can have some influence on the 
page layout
For this one easy to do thing is to split the page in graphical subpart 
and to allow to
change the layer, for example www/include/project_home.php should be 
splited in

www/include/project_home.php.desc
www/include/project_home.php.contacts
www/include/project_home.php.frs
www/include/project_home.php.jobs
www/include/project_home.php.news
www/include/project_home.php.pubarea
www/include/project_home.php.stats

www/include/project_home.php would make simple includes

and you could at the beginning of www/include/project_home.php test if 
there is some kind of www/include/project_home.php.plugins_name
if the layout requires to be redone

> [TODO: Specify these hooks and how they work, implement]
>  Additionnally, a series of hooks will be provided so that plugins do
> not need to change existing files for simple insertion.  For instance,
> if the "acmecvsinterface" does not have particular needs besides a
> link pointing to it from the project page, it could just register its
> base URL to the "project-menu-features-list-hook", and the project
> menu would display a list of links subscribed to that hook with one
> parameter, "?group_id=<group_id>".
>
> - Plugin-specific web pages should reside either in the /plugin/*/
> URL-space (that is, plugin "foo" will probably put its files in
> /usr/lib/sourceforge/www/plugins/foo/) or (if the web interface is not
> written in PHP) in /plugin/*/cgi-bin/ URL-space (files in
> /usr/lib/sourceforge/cgi-bin/plugins/foo/).
>
>  If possible, and as much as possible, a plugin should use the layout
> functions defined by Sourceforge (Layout.class, HTML.class, or
> whatever they're called), to ensure a consistent look and themability.
>
>  Of course, the previous point only applies to plugins written in
> PHP.  Plugins written in other languages are not excluded by this
> proposal, and there is no need to restrict them.  Should they appear,
> they might need to recode some of Sourceforge's functions in Perl or
> another language.  I see no need to restrict that either.  Only thing:
> it would be better if the porting were as straightforward as possible.
> Do not reimplement, please.  Just translate from PHP to Perl or
> whatever.  If you do, please submit your translation to us, so that it
> can be provided by Sourceforge proper and maintained in common.
>
> [TODO: Think about that, design, implement]
>  Speaking of languages...  There should be some way to have
> plugin-specific language files, so that the plugins can use the
> standard methods used elsewhere in Sourceforge.  I haven't thought
> about that very deeply yet, but I think it will evolve into a
> recommendation that the "handles" in the language files are
> plugin_foo_page / item (as compared to the current page / item model
> used for "core" Sourceforge i18n strings).
>  
Just use the mecanism you used for langage_local is enough

What is done with langage could also be used for plugins
That would allow you to choose the various parameter of a plugins with a 
set of standart one in Base
I would suggest a www/include/plugins/Base.tab
and various www/include/plugins/plugin_name.tab
Base would contain
<page name> <TAB><function_name><TAB><function implementation>
And every time a plugin needs to change a function you would had to 
change the normal call to call the funtion
$Plugins->getFunc('pagename','functionname')

> [TODO: Implement those scripts]
> - A plugin should register itself into the database using the provided
> sf-register-plugin script on its installation, and deregister itself
> using sf-deregister-plugin on removal.
>
> HOW DO I MAKE A PLUGIN?
> -----------------------
>
> [TODO: Actually implement it...]
>  Your best bet would be to start with the sample "helloworld" plugin
> and change parts of it.  It shows an example of everything you should
> need to make your plugin: PHP pages, Perl CGI pages, configuration
> files, bits of Apache configuration, cron jobs, etc.  If you need
> something else, please ask, we'll discuss it, (hopefully) reach an
> agreement on how to Do It Right, and implement a sample in
> helloworld.
>
>
>  -- Roland Mas <address@hidden>
>  
Cheers

Christian