Skip to end of metadata
Go to start of metadata

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 !

Project naming

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: foobar would be an example matching the above.
  • Java packages: preferably your own package structure (org.foobar.myproject) or info.magnolia.forge.<yourproject> (i.e we want to avoid conflicts with other info.magnolia packages and groupID; if your own "package structure" is info.magnolia, the no need to add the .forge suffix)
  • 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.

(warning) 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.

Maven build

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. See Maven Parent POMs.

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.

Also see Maven setup to setup your Maven environment (i.e. settings.xml).

Not using our parent pom

If you just want to deploy to the Forge Maven Repository, you'll just need this snippet in your pom.xml:

Quality criteria

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.
  • ... ?
Labels
  • None
  1. Oct 29, 2010

    Greg,

    Very nice start, thanks. A couple comments:

    Java packages: do we want to (gently) disallow the usage of info.magnolia package names ?
    Group ID: (the technical identifier used in Maven repositories to distinguish artifacts) same as above.

    Instead of disallowing info.magnolia, why not require an additional suffix identifier? For example, info.magnolia.forge, which is actually in conformance with package2domain naming conventions, forge being the subdomain. Additionally, the forge parent pom could set it's groupId to info.magnolia.forge? Doing so would help group conforming forge projects together in repository managers. I think it would also feel a bit more natural, since the parent pom would have a groupId that made sense with the projects that inherit from it. So using twigs as an example:

    What do you think?

    Thanks,
    Matt

  2. Oct 29, 2010

    Another idea might be to use com.magnolia_cms.forge, which would change the above pom snippet to:

    I'd be good with this approach, although I don't particularly like underscores.

    Ok, that's all I got for now. (smile)

    Cheers,
    Matt

  3. Oct 29, 2010

    I think keeping info.magnolia is fine (instead of the more cumbersome com.magnolia_cms) but really I don't mind either way.

    1. Oct 29, 2010

      Yeah, as a sub(package/group), yes. Our own groupID is already too cluttered.
      BUT: GroupIDs are supposed to be stable (to allow dependency resolution to still work in 475 versions from now) - so if a project wants to fork (or we buy it out(wink)) they'd theoretically have to live forever with the "forge" appendix, while they've matured to a newer home.
      I guess that'll be up to the developer's to make their choice wisely.

  4. Oct 04, 2014

    Out of Date Links found here: http://forge.magnolia-cms.com/ :

    I can't figure out the right working URLs for the 3 News feeds -  with https it takes long time, I think I will get an timeout, if I wait.
    Suggestions for improvements:
    1. Text Changes:
      1. Official Magnolia Website (english) -> Official Magnolia Website
      2. Share your modules ! -> Why share modules?
        1. Highlight at end of text an button-link with the message "Want to register a project?"
        2. Highlight at end of text an button-link with the message "Follow the Discussions about Forge on Wiki."
    2. Give the Page an Title:
    3. Give the Page some coloring.. looks currently like a grey Wall:
      1. <script src="http://pastebin.com/embed_js.php?i=qcmte77F"></script>
        example prepared css