Publish a module, theme, or distribution on Drupal.org
Publishing on Drupal.org - Overview
The process of applying for permission to create a Full project has changed as of March, 2017. Developers looking to publish a Full project are encouraged, but not required, to apply for permission to opt into security advisory coverage, and I wanted to know for myself how this process works.
There are several detailed steps required to publish a new project on Drupal.org. But, the investment is well worth your time. This article will cover:
- What has changed as of March, 2017
- Why hosting your project on Drupal.org is a good idea
- Comparing Full and Sandbox projects
- How to create a Sandbox project
- Promoting a Sandbox project to a Full project
- Applying for permission to opt into security advisory coverage
What has changed as of March, 2017
Providing developers with an ecosystem for sharing new ideas, while simultaneously assuring customers that code has been tested for stability and security, is a constant challenge in any open source realm, and Drupal is no exception.
Prior to March 2017, publishing a project on Drupal.org as a relative newcomer would easily mean a year-long wait (or even indefinite). Developers could create a sandbox module, but converting it to an "official" module was a big challenge. The creator of the sandbox needed to get the module reviewed and "approved". Once approved, they would not need to go through the process again. But, it was a long process, and many developers got frustrated by this inefficient "approval" process. The only way to speed it up was to review other projects (resulting in a review bonus), but this was still very time consuming. This process worked when Drupal was still small, but the community has grown (nearly 4,000 people have contributed to Drupal 8 core alone!), and there are simply not enough volunteers to review and approve / disapprove new modules, themes, or distributions.
Beginning in March 2017, any Drupal.org user may create at least one Full project or promote at least one Sandbox project to Full at any time.
However, even though anyone may create a Full project, Full projects are not automatically covered by the Drupal Security Team, and users are encouraged to follow Drupal.org best practices prior to promoting their project to Full status, regardless of Security Team review.
Changes to this promotion process have been debated heavily for several months over at Drupal.org, and some new philosophies were adopted that will govern this promotion process going forward:
- Reduce the feeling there are two tiers of users; those who can contribute code freely, and those who cannot.
- Prevent insecure and poorly coded modules from being published on Drupal.org. This is a major concern for the Security Working Group, which is responsible for Security Advisories for contributed projects, as well as core.
- Let sandbox users get a release that is installable. This is one of the biggest desires of users waiting for approval. They want a release for their module they can link to and share.
- Let sandboxes reserve a namespace so that every project has a proper project page and url.
- Reduce the amount work a review requires by reducing the rigor with which reviews must be completed.
The policy revamp debated above resulted in a Community Initiative Proposal, which is aiming to enforce the following high-level policies:
- The git user role (which any confirmed user can get by agreeing to the terms) will be able to:
- Create any number of projects (we will need a better policy for abundant namespaces)
- Create any releases for those projects
- All new projects will have a new option to opt in to security team coverage.
- Those that do not, will get a warning message on the project page and on the update status page for their sites. (this will require core updates for the update status)
- A role is required to opt in to security team coverage. We can repurpose the “git vetted user” role to “Opt into security team coverage”
- For now, to get the new “Opt into security team coverage” role, we will use basically the current project application process - however instead of being a gate on new project contribution, it is only a gate on participating in security team coverage.
- Because this opt-in process is now decoupled from the project creation/release process and is wholly in the domain of security coverage it can be replaced by a coding standards quiz or whatever the SecWG decides will best manage their work, sometime in the future.
Why hosting your project on Drupal.org is recommended
While there are many other places where you may host your project (GitHub, BitBucket, personal server, etc.), the Drupal community strongly encourages developers to host their projects on Drupa.org for the following reasons, as explained on Drupal.org:
- Community owned - Drupal.org is owned by you the community users and the not-for-profit Drupal Association (DA). The DA's first priority is to serve its users. Drupal.org is not owned by a Corporation. So, there is no interference from Corporations. Corporations are really welcome, but as contributors and not as owners.
- Larger User Base - Most users check Drupal.org first and assume the project doesn't exist if it's not there.
- Consistency Is Understandable - It is much easier for someone new to Drupal to understand how to download and install themes/modules from a central location rather than 3 or 4 central locations.
- Unified Issue Tracker - "My Issues" will show any issues you are subscribed to for any Drupal project, instead of having to go to different sites to check up on issues you follow.
- Usage Statistics - Any project or theme on Drupal.org has tracked usage statistics via the Update Status module.
- Update Notifications - A Drupal website will notify (even email if you prefer) you when a Drupal.org project is updated via the Update Status module.
- Programmatic Updates & Downloads - Hosting everything at Drupal.org means that Drush, Aegir, Plugin Manager, etc. can all have a uniform method of downloading and updating projects.
- Encouraging Activity - Users are more encouraged to contribute bug reports, patches, etc., if they only have to do so in one place, with one account, and one set of skills.
- Co-contributors - It is trivial to add more git contributors to your Drupal.org project, and more difficult if these contributors would have to be set up in an external site.
- Install Profile Integration - Drupal's Install Profiles give you pre-packaged versions of Drupal, complete with all required modules and themes. They cannot do this if any of the modules or themes are not hosted on Drupal.org.
Comparing Sandbox projects and Full projects
Sandbox projects and Full projects share some key basic features, such as both having a project page, a Git repository, an issue queue, and the ability to appoint co-maintainers.
But, there are some distinct differences between a Sandbox and a Full project, meant to steer developers toward trustworthy and stable projects. The following table summarizes some of these differences.
|Sandbox projects||Full projects|
3-Step Guide to Publishing Your Project on Drupal.org
Creating a Sandbox project
First, obtain git access for your Drupal.org account.
- Navigate to your account page and click the Git access tab.
- Go over to the SSH keys tab, and add a public ssh key.
You may then proceed with creating a Sandbox project.
- Fill out the form. Your new project will initially be a sandbox project. If you have permission to promote projects from Sandbox to Full projects, you will see a checkbox allowing you to choose Full project, but normally it is best to start with a Sandbox anyway.
Click the Save button. Drupal creates and loads a page for your new project.
Click the Version control tab near the top of the new project page for instructions on how to start committing code to your sandbox repository.
Your project will now appear on your Your Projects page. If desired, grant access to other users by editing the Maintainers section.
Promoting your Sandbox project to Full project status
Even though Security Team approval is not required, Developers should refrain from promoting their projects until they have been thoroughly tested, proper documentation has been created, and possible security holes have been considered.
When you are ready to promote your project to Full status:
- Acknowledge that promoting a project may not be undone, enter a short project name (using all lowercase characters), and select to enable releases.
- Click Promote, and confirm that you are ready to promote.
Re-clone your project in Git, or update your remote URL in your existing local code repo, to be able to continue updating your project
Applying for permission to opt into security advisory coverage
Drupal.org provides detailed instructions for applying for this permission, the most notable steps of which I have excerpted here:
- Before entering the project application process, you should first make sure that your project is a release candidate (RC). You don’t have to make the tags and releases right away - your project should measure up to the RC standard. Entering the process too early with a poorly documented and buggy project will usually result in the review process taking a much longer time than necessary.
- Have a look at the Project application checklist, and try to resolve common issues.
- Once ready, create a new issue in the Project Applications queue [Note: Do NOT edit that page! Create a new issue.].
- Fill out the issue form:
- [Dx] Your project name
- Use [D6], [D7] or [D8] to specify which Drupal version your project uses.
- e.g. [D7] Unicorn Integration
- Project: Drupal.org Project applications
- Category: task
- Status: needs review
- Component: 'module', 'theme' or 'feature' (depending on the application)
- A detailed description of what your project does, including how it is different from other, similar projects, if applicable.
- For themes it's helpful to include a screenshot.
- A link to your project page. As for the contents of your project page, you may want to use the Project page template as a guide, and it may be a good idea to also read tips for a great project page.
- A git clone command. You can find the correct git clone command for your sandbox by clicking on the Version control tab, removing the checkbox in front of "Maintainer", and clicking Show. You can then copy-paste the git clone command from the codeblock below "Setting up repository for the first time". The git clone command should be version specific, for example, 7.x-1.x branch for Drupal 7 version as below.
git clone --branch 7.x-1.x email@example.com:sandbox/username/123456.git module_name
- A list of links to reviews of other project applications that you did.
Reviewers will examine your code and may provide feedback and concerns about your project (See the Drupal.org article: What to Expect). This process can take weeks or even months, but it can be accelerated by participating in the Review bonus program.
Once this process is complete, you will be able to promote your project to Secured status, and you will finally have that beautiful "Shield" icon alongside your stable release indicating that your project is officially covered by Drupal's Security Advisory Policy.
Contributing new projects to Drupal.org is now easier and will allow more developers to make use of all the possibilities Drupal.org offers, like releases, drush download, etc. But, don't give up on security coverage! The "Opt into security team coverage" is a proof of quality for your contributed module, theme, or distribution. It makes people more confident to use your work. The validation process will probably remain hard and slow, but it is worth it. Reviews and tests improve the quality of contributions all the time!
The mission of any Open Source platform is for people to share code and ideas among those in its community, and Drupal is no exception! Publishing your project, and eventually opting into security coverage, will not only strengthen Drupal's offerings, but it will contribute to your own reputation as a relevant and meaningful contributor to Drupal's mission. Happy coding!
References and Special Thanks
Useful references, and further reading:
- [policy, no patch] Changes to the project application review process
- [Community Initiative Proposal] Project Applications Process Revamp | Drupal.org
- Why host your project on Drupal.org | Drupal.org
- Creating and testing full projects and releases | Drupal.org
- Creating a sandbox (experimental) project | Drupal.org
- Obtaining Git access | Drupal.org
- Create a sandbox project | Drupal.for permission to opt advisory coverage | Drupal.org
- Review process for security advisory coverage: what to expect | Drupal.org
- Promoting sandbox projects to full projects