Top Menu

Jump to content
Home
    • Projects
    • Work packages
    • News
    • Getting started
    • Introduction video
      Welcome to OpenProject Community
      Get a quick overview of project management and team collaboration with OpenProject. You can restart this video from the help menu.

    • Help and support
    • User guides
    • Videos
    • Shortcuts
    • Community forum
    • Professional support

    • Additional resources
    • Data privacy and security policy
    • Digital accessibility (DE)
    • OpenProject website
    • Security alerts / Newsletter
    • OpenProject blog
    • Release notes
    • Report a bug
    • Development roadmap
    • Add and edit translations
    • API documentation
  • Sign in
      Forgot your password?
      Create a new account

      or sign in with your existing account

      Google

Side Menu

  • Overview
  • Activity
  • Roadmap
  • Work packages
  • Calendars
  • Team planners
  • Boards
  • Forums
  • Wiki
    • Table of contents
      • Expanded. Click to collapseCollapsed. Click to showDeveloper
        • Hierarchy leafAccessibility Checklist
        • Hierarchy leafCode Review Guidelines
        • Expanded. Click to collapseCollapsed. Click to showContribution
          • Hierarchy leafGit Workflow
          • Hierarchy leafTranslations
        • Expanded. Click to collapseCollapsed. Click to showDeveloping Plugins
          • Hierarchy leafDeveloping an OmniAuth Authentication Plugin
        • Hierarchy leafRelease Process
        • Hierarchy leafReport a bug
        • Hierarchy leafSecurity
        • Hierarchy leafSetting up an OpenLDAP server for testing
        • Hierarchy leafTheme Features
      • Hierarchy leafDownload
      • Expanded. Click to collapseCollapsed. Click to showFeature tour
        • Hierarchy leafRelease Notes OpenProject 30
        • Expanded. Click to collapseCollapsed. Click to showRelease Notes OpenProject 30 - Overview
          • Hierarchy leafGlossary
          • Hierarchy leafRelease Notes - Accessibility
          • Hierarchy leafRelease Notes - Accessibility changes
          • Hierarchy leafRelease Notes - Add work package queries as menu items to sidebar
          • Hierarchy leafRelease Notes - Copy projects based on Templates
          • Hierarchy leafRelease Notes - Design changes
          • Hierarchy leafRelease Notes - Fixed Bugs
          • Hierarchy leafRelease Notes - Keyboard Shortcuts
          • Hierarchy leafRelease Notes - Project settings
          • Hierarchy leafRelease Notes - Ruby&Rails Update
          • Hierarchy leafRelease Notes - Security
          • Hierarchy leafRelease Notes - Timelines
          • Hierarchy leafRelease Notes - Work packages
      • Hierarchy leafHowto create animated gifs
      • Hierarchy leafMigration Squashing
      • Hierarchy leafMod security
      • Hierarchy leafNew work package page
      • Hierarchy leafOP3 to OP4 Debian upgrade
      • Hierarchy leafOP4 Ubuntu1404 Stable with MySQL in production
      • Hierarchy leafOpenProject 40 Development Setup
      • Expanded. Click to collapseCollapsed. Click to showOpenProject Foundation
        • Hierarchy leafBoards
        • Hierarchy leafMembers
        • Hierarchy leafOPF-Meetings
        • Hierarchy leafStatutes
      • Expanded. Click to collapseCollapsed. Click to showRelease Notes
        • Hierarchy leafOpenProject released on Bitnami
      • Expanded. Click to collapseCollapsed. Click to showRelease Notes OpenProject 40 - Overview
        • Hierarchy leafRelease Notes OpenProject 40 - Accessibility improvements
        • Hierarchy leafRelease Notes OpenProject 40 - Column header functions in work package table
        • Hierarchy leafRelease Notes OpenProject 40 - Improved Design
        • Hierarchy leafRelease Notes OpenProject 40 - Integrated query title on work package page
        • Hierarchy leafRelease Notes OpenProject 40 - Integrated toolbar on work package page
        • Hierarchy leafRelease Notes OpenProject 40 - OmniAuth integration for OpenProject
        • Hierarchy leafRelease Notes OpenProject 40 - Work package details pane
      • Expanded. Click to collapseCollapsed. Click to showSecurity and privacy
        • Hierarchy leafFAQ
      • Expanded. Click to collapseCollapsed. Click to showSupport
        • Expanded. Click to collapseCollapsed. Click to showDownload and Installation
          • Hierarchy leafInstallation MacOS
          • Expanded. Click to collapseCollapsed. Click to showInstallation OpenProject 3 0
            • Hierarchy leafDebian Stable with MySQL in production
            • Hierarchy leafInstallation Ubuntu
            • Hierarchy leafInstallation Windows
            • Hierarchy leafInstallation on Centos 65 x64 with Apache and PostgreSQL 93
          • Expanded. Click to collapseCollapsed. Click to showInstallation OpenProject 40
            • Hierarchy leafOP4 Debian Stable with MySQL in production
          • Expanded. Click to collapseCollapsed. Click to showMigration paths
            • Hierarchy leafFrom Chilliproject to OpenProject
            • Hierarchy leafMigration 15 to 30
            • Hierarchy leafMigration 24 to 30
            • Hierarchy leafMigration Redmine 2x › OpenProject 30
            • Hierarchy leafOpenProject 3 Migration
          • Hierarchy leafOpenProject 40
        • Expanded. Click to collapseCollapsed. Click to showNews
          • Hierarchy leafNew OpenProject Translations Plugin
          • Hierarchy leafNew Plugin on OpenProjectorg Local Avatars
          • Hierarchy leafNew design for OpenProject
          • Hierarchy leafNews Accessibility workshop for OpenProject
          • Hierarchy leafNews Glossary for OpenProject
          • Hierarchy leafNews Heartbleed fixed
          • Hierarchy leafNews Icon Fonts
          • Hierarchy leafNews OpenProject 30 Release
          • Hierarchy leafNews Release GitHub Integration Plugin
          • Hierarchy leafNews Success Story Deutsche Telekom
          • Hierarchy leafNews Timelines
          • Hierarchy leafOpenProject 3013 released
          • Hierarchy leafOpenProject 3017 released
          • Hierarchy leafOpenProject 40 released
          • Hierarchy leafOpenProject 40 will be coming soon
          • Hierarchy leafOpenProject 405 released
          • Hierarchy leafOpenProject and pkgrio
          • Hierarchy leafOpenProject news moved to a new blog
          • Hierarchy leafOpenProjectBitnami
          • Hierarchy leafPackager version with plugins released ("Community edition")
          • Hierarchy leafRegistration OpenProject-Foundation
          • Hierarchy leafRelease OpenProject AuthPlugins
          • Hierarchy leafUpdates on OpenProject
          • Hierarchy leafWe need your feedback for the the new fullscreen view for work packages
        • Hierarchy leafOpenProject Plug-Ins
      • Hierarchy leafWiki
You are here:
  • Developer
  • Developing Plugins

Content

Developing Plugins

  • More
    • Print
    • Table of contents

Developing Plugins

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 a_good_name ../plugins/

This generates the plugins openproject-a_good_name into the directory ../plugins/openproject-a_good_name. The new plugin is a rails engine, which can be published as a gem. Please edit the openproject-a_good_name.gemspec file to be ready.

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 line to Gemfile.plugins:

gem "openproject-a_good_name", :path => '../plugins/openproject-a_good_name'

and install it via

bundle install

Start coding

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:

Code Review

A code review should check the whole code and remove glitches like:

  1. Unappropiate comments
  2. Deactivated code
  3. Minor cases of code smell

Resolve licensing and copyright issues

  1. 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:
rake copyright:authors:show['../Path/to/repository/']
  1. 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.
  2. 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
    1. If you’re unsure about if/who to give credit, you should take a look into the changelog:

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


rake copyright:authors:show\[‘../Path/to/repository/’\]

  1. Licensing information.
    It is probably best to use READMEs of already released plugins as a template.

Complete the gemspec

  1. Add the license to the gemspec of the plugin if not already there.
  2. Add any files that should be included to the gemspec (e.g. the doc folder, the db folder if there are any migrations, the CHANGELOG.md, and the README.md).
  3. Check authors and email point to the right authors.
  4. The homepage should be the homepage of the plugin.
  5. Check if summary and description are there.
  6. 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.
  7. 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.
  8. Push the version of the plugin, mostly by just removing any .preX specials at the end.
  9. Don’t forget to add a changelog entry. :)
  10. Commit everything.
  11. Also create a release tag (named ‘release/’ for example ‘release/1.0.2’) to name the new version.
  12. 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 .gemspec
  • gem push -.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
  • 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

  1. Make the github repository public.
  2. 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.
  3. Create a news article about the newly released plugin and its features.
  4. Twitter with a link to the news article.
  5. If the plugin is referenced in our feature tour, add a download link to the plugin in the feature tour
  6. Add the newly released plugin to the list of released plugins
Loading...