Tuesday 26 February 2013

MapGuide tidbits: RFCs

For this post, I'm going to shed a little insight into those things called RFCs.

Having submitted several RFCs for MapGuide which have been fully realised into new product features, I think I am qualified to share some insight into how RFCs work. Unlike the formal Wikipedia definition, we're going to be talking about RFCs strictly in context of the MapGuide Open Source project.

What are RFCs?

RFCs (Request For Comments) can be generally thought of as detailed proposals for a new feature or enhancement for MapGuide.

Anyone can submit an RFC, but writing an RFC is more than just "MapGuide needs to do X or support Y" as you'll hopefully see below.

How do RFCs differentiate from enhancement tickets?

Enhancement tickets are generally micro-level in nature, RFCs are macro-level in nature that have broad implications to MapGuide as a product and platform. Enhancements that would affect any of the following areas are usually candidates for an RFC proposal and some level of discussion first with the Project Steering Committee:

  • API additions/updates/removal. (eg. RFC9)
  • A new type of resource. (eg. RFC108)
  • A resource XML Schema update. (eg. RFC16)
  • Support for new(er) standards. (eg. RFC106)
  • Major user-facing product features/enhancements. (eg. RFC24RFC71)

What RFCs are not

As already mentioned, RFCs are not enhancement tickets, not just in scope but also in purpose.

Enhancement tickets follow a simple formula: "I wish this part of MapGuide could do X" and the rest will then be left as an open exercise for any interested contributor to see if it can be implemented. Or, such tickets will already have a patch included, which makes our jobs much easier :)

RFCs on the other hand, will generally have implementation work done up-front due to their broad scope. Actually I would imagine that most RFCs posted for discussion will have at least 70% of the implementation work already done and the remaining 30% to be filled in as a result of discussions on mapguide-internals or adoption/approval by the Project Steering Committee.

RFCs submitted without any plan of implementation or a 70%-100% working implementation up-front will generally go nowhere. It's not like Autodesk, myself or anybody in the Project Steering Committee is going to help fill in the blanks for you. We'd comment here and there (as needed for an RFC discussion), but ultimately there has to be work done (or to be done) by you (the RFC submitter) or a clear detailed plan of implementation.

RFCs are basically your proposed plan for a new feature/enhancement:

  • Here's a idea for a new feature/enhancement for MapGuide
  • Here's some scenarios or reasons where we need such a feature/enhancement
  • Here's how this new feature/enhancement would be implemented. Where applicable, here's a link to a SVN branch or a build where this feature is already implemented, so you can see for yourself how this feature looks and works.

Such RFCs will have enough meat and potatoes in them for the Project Steering Committee to discuss and vote on for formal adoption into the MapGuide Open Source project.

My process for submitting RFCs

Let me illustrate the life-cycle of an RFC with some examples from RFCs I've personally submitted and seen through to implementation.

1. The idea

When I have an idea, I make a sandbox branch from trunk and start hacking and playing around. As you can see, many RFCs I've submitted started life as sandbox branches. The benefit of doing RFC work on a sandbox branch is that upon adopting by the Project Steering Committee, integration into MapGuide is a simple svn merge away.

2. Drafting the RFC

Once the implementation in my sandbox branch is 70-90% complete, I then move on to drafting up the RFC. This covers the above bullet points in as much detail as possible.

3. mapguide-internals discussion

I then submit this RFC to the mapguide-internals mailing list for discussion. This generally takes 1-2 weeks, which is generally enough time to address any concerns or unknowns in the RFC. After this period, if there's no opposition, the RFC gets called to a vote for adoption. If the RFC does not get adopted (very unlikely in most cases), I'd stop at this point. Otherwise, I move on to the next step.

4. Filling the blanks

The remaining 10-30% of the implementation is then completed based on feedback on the RFC, or if there isn't much feedback, the original implementation plan as stated in the RFC.

5. Merge back into trunk

Since the implementation work is in a sandbox branch, re-integration back into trunk is just a simple merge away. The RFC at this point is complete.

In closing

Hopefully this post has somewhat de-mystified RFCs in the MapGuide Open Source project and may give you some confidence to submit one of your own in the near future.

No comments: