Create an OpenProject plugin
OpenProject plugins are special ruby gems. You may include them in your
Gemfile.plugins file like you would do for any other gem. Fortunately, this gives us plugin version management and dependency resolution for free.
Generate the plugin
You can generate a new plugin directly from OpenProject. Think of a good name and a place (in your filesystem) where the plugin should go. In this example, we have a
plugins directory right next to the
openproject directory. Then do
bundle exec rails generate open_project:plugin my_plugin ../plugins/
This generates the plugins
openproject-my_plugin into the directory
../plugins/openproject-my_plugin. The new plugin is a rails engine, which can be published as a gem.
You may want to update the generated plugin's gemspec (
There is an example plugin which does some of the basic things (adding menu items, hooking into views, defining a project menu, etc.) and provides further info in its README.
Instead of generating a new plugin you can also just clone the example plugin and adapt it.
Hook the new plugin into OpenProject
To include the new plugin into OpenProject, we have to add it into
Gemfile.plugins like any other OpenProject plugin. Add the following lines to
group :opf_plugins do gem "openproject-my_plugin", :path => '../plugins/openproject-my_plugin' end
If there already is an
opf_plugins group, just add the
gem line to it.
Once you've done that install it via
You may have a look at some existing OpenProject plugins to get inspiration. It is possible to add new routes, views, models, … and/or overwrite existing ones.
Feel free to ask for help in our Development Forum.
Steps to release a plugin
The following steps are necessary to release a new plugin:
A code review should check the whole code and remove glitches like:
- Unappropiate comments
- Deactivated code
- Minor cases of code smell
Resolve licensing and copyright issues
- Check the license and the copyright of the plugin to be released
Usually, this should be GPLv3 and we are the copyright owner. However, some plugins might have additional authors or might originate from code with a different license. These issues have to be resolved first. Also check the years in the copyright. If you need to find all contributors of a repository including their contribution period use the following rake task:
2. Add a copyright notice to all the source files There is a rake task in the core to perform this job. Use `rake copyright:update['path_to_plugin']` (e.g. `rake copyright:update['../plugins/openproject-global_roles']`) to add the copyright header in `doc/COPYRIGHT_short.md` to all relevant plugin files. If no such file exists, `doc/COPYRIGHT_short.md` from the core is used. 3. Check for existence of `doc/COPYRIGHT.md` and `doc/GPL.txt` if referenced by the copyright notice. ### Complete the readme file or add one if not existing There should be a file README.md containing: 1. A description about what the plugin is actually doing 2. Requirements to use the plugin 3. Instructions how to install and uninstall a plugin 4. Notes where to report bugs 5. Notes where to contribute 6. Credits If you’re unsure about if/who to give credit, you should take a look into the changelog: ```bash git log --pretty=format:%aN | sort | uniq -c | sort -rn
For your convenience you may use the following rake task, that extracts all authors from a repository
- Licensing information. It is probably best to use READMEs of already released plugins as a template.
Complete the gemspec
- Add the license to the gemspec of the plugin if not already there.
- Add any files that should be included to the gemspec (e.g. the
dbfolder if there are any migrations, the
CHANGELOG.md, and the
- Check authors and email point to the right authors.
- The homepage should be the homepage of the plugin.
- Check if summary and description are there.
- Check if all dependencies are listed (this might be difficult, I know): There should be a sentence in the README, that this is an OpenProject-Plugin and requires the core to run. Apart from that, state only dependencies that are not already present in core.
- While you are at it, also check if there is any wiring to core versions necessary in engine.rb; also check, that the url of the plugin is wired correctly.
- Push the version of the plugin, mostly by just removing any .preX specials at the end.
- Don’t forget to add a changelog entry.
- Commit everything.
- Also create a release tag (named ‘release/
’ for example ‘release/1.0.2′) to name the new version.
- Push the tag with
git push --tags.
Publish the gem at Rubygems
gem update --system
- Ensure gemspec fields are complete and version number is correct
gem build <name>.gemspec
gem push <name>-<version>.gem. This asks for your user/password
- Go to https://rubygems.org, log in, go to the dashboard, click on the uploaded gem, click edit. Set URLs, at least source code URL and Bug Tracker URL
- You are done .
- Be careful when publishing a gem.Once it is published, it cannot be replaced in the same version. It is only possible to take a version out of the index and publish a new version.
Create public visibility
- Make the github repository public.
- Make the plugin project public. Do a little cleanup work first by removing modules not needed. Currently, Activity, Issue Tracking, Time Tracking, Forums, and Backlogs are default. Also, the My Project Page should only show Project Description and Tickets blocks.
- Create a news article about the newly released plugin and its features.
- Twitter with a link to the news article.
- If the plugin is referenced in our feature tour, add a download link to the plugin in the feature tour
- Add the newly released plugin to the list of released plugins.
Frontend plugins [WIP]
Plugins that extend the frontend application may be packaged as npm modules.
These plugins must contain a
package.json in the root directory of the plugin.
Plugins are responsible for loading their own assets, including additional images, styles and I18n translations.
Translations are processed by I18n.js through Rails and will be picked up from
Pure frontend plugins are currently not possible without modifications to the OpenProject core
We instead recommend to create a hybrid gem plugin instead (see below).
Plugins that extend both the Rails and frontend applications are possible. They
must contain both a
CAVEAT: npm dependencies for hybrid plugins are not yet resolved.
To use a hybrid plugin:
declare the dependency in
:opf_pluginsgroup using the Bundler DSL.
Provided Ruby Bundler is aware of these plugins, Webpack (our node-based build pipeline) will bundle their assets.
You can find the master document in GitHub. You can propose a change to this guide by creating a pull request on GitHub.