This page is work in progress; please contribute !
What IS a Forge Project ?
A Magnolia Forge project is a project, usually in the form of a Magnolia module, or sometimes a complete web application, but can also be STK themes, documentation, procedures, examples, what have you. If you're willing to share any of this with the Magnolia Community, you are more than welcome to apply !
What about Magnolia's own Forge projects ?
The above was a little unclear for a while when we started out with the Forge, and as such, we have added a couple of projects on the Forge which should not have gone there. Magnolia employees, partners and other consultants will still use the Forge, but when adding a new module, we're thinking about it this way: if the module is meant to be maintained by, bundled with the product of, and supported by the Magnolia CMS company, then that module will most likely not start on the Forge. However, there are examples of modules that are started as "side" or hobby projects by members of the Magnolia team, and/or are maintained jointly with community members, and those will remain on the forge !
The following few "rules" are currently being ironed out; they're not strictly enforced, but it's always appreciated if you comply. Feel free to diverge and/or raise any concern or ideas you might have !
- Project name: to distinguish between products delivered by Magnolia International (the company) and third parties, we might suggest using names such as "Foobar", "Foobar (for Magnolia)", or "Foobar Magnolia Module" (with or without the parenthesis); whereas Magnolia International's own modules are named "Magnolia Bazqux Module". This might also mean we'd need to revise consistency in our own modules.
- Short name:
foobarwould be an example matching the above.
- Java packages: preferably your own package structure (
info.magnolia.forge.<yourproject>(i.e we want to avoid conflicts with other
info.magnoliapackages and groupID; if your own "package structure" is
info.magnolia, the no need to add the
- Group ID: (the technical identifier used in Maven repositories to distinguish artifacts) same as above; please use a groupID per-project.
- License headers: up to you. See #Maven build if you want to use our parent pom, which provides a lot of pre-configured options and plugins.
Many projects or modules are all about "integration"; integrating X with Magnolia. Those are often difficult to name, in that you can't just call them "x". Some projects came up with great "code" names (Blossom, Maglev, Twigs, Frisbee, ...) and some just kept the "x" part. It's usually fairly obvious what these modules are about, when hosted on our systems (i.e thanks to the URL, I guess), but perhaps not so much when mentioned outside. Think about it !
Contributing to a Forge project
There are many ways you can contribute to a project hosted on the Magnolia Forge (much like any other open source project, really).
- Talk about it. Blog about it. Document your experience.
- Report bugs, or ideas for improvement, on the project's own issue tracker.
- Report bugs... and provide patches for it ! Attach patch files to the bug report.
- Get the project's maintainer(s) to like you by submitting several, useful patches. Or who knows, just by talking with them.
How to add contributors to your project
So there's this person who's contributing a few good patches to your Forge project, or is just being nice, and you'd like to get them to contribute directly, by committing in the source repository, and/or being able to assign issues to them. How to proceed ? Simply go reopen and edit your FORGE@jira registration and add them in the "Developers" box.
note: this is valid for all projects. New Magnolia employees might be a little disconcerted by this, since they might be used to be able to commit everywhere else on our source repository. Eh.
Using the Forge parent pom
A parent pom for Forge projects is available on our repositories. Using it is not mandatory at all, but it could provide a quick start for new projects.
Projects which want to can use it: (feel free to report issues or RFEs on BUILD@jira)
See http://svn.magnolia-cms.com/svn/forge/forge-sample/trunk/pom.xml for an example of the few elements that have to be re-defined in your own pom. Also check out Module QuickStart for ways to quickly set up your project.
Properties and other configuration
Our parent poms provide a whole slew of pre-configured plugins. You're of entirely free to reconfigure anything you want. Feel free to ask if anything is unclear, if anything needs to be changed (BUILD@jira) or if you don't know how to achieve something specific.
Here's a (possibly incomplete) list of properties our parent poms use which you can possibly (re-)configure:
checkstyleHeader: default is
magnolia-build-tools/license-header-ignored.regex. Provide a path to your license header regular expression to force a check on your prefered header. As examples, you can check out ours in the magnolia-build-tools project.
cloverLicense: (embedded license key, set in
cloverLicenseLocation: (set in
~/.m2/settings.xml- as an alternative to the embedded license above)
cloverCoverageThreshold: as from parent-pom v20, builds will fail if the given threshold is not reach. Default value is 0.
magnoliaProjectBundleType: this property can be used by certain bundles to drive the contents of the README.txt from magnolia-build-tools
Also see Maven setup to setup your Maven environment (i.e.
Not using our parent pom
If you just want to deploy to the Forge Maven Repository, you'll just need this snippet in your
This is just an idea that's been in the back of my head for a while, but I thought it might help, both developers, to improve their projects, and users, to select the projects they want to use, to have some Magnolia-validated quality criteria on Forge projects, such as:
- build quality: deploys properly to our repo, CI builds are stable, following naming conventions, good coverage, etc.
- licensing compatibility
- good practices, code quality: this would probably the most time-consuming to grant, but some extra "star" icon next to a project might be lovely; if the project follows what Magnolia considers to be good practices, uses the existing Magnolia APIs, integrates well with other modules, etc.
- ... ?