Wednesday 6 February 2013

MapGuide tidbits: Support and User Expectations

I didn't want to have to write this post, but I have no choice. Consider this a Public Service Announcement.

When you buy a licence for Autodesk Infrastructure Map Server, you're not just buying the product, you are also buying for product support from Autodesk or their reseller partners.

For MapGuide Open Source, there is no formal product support.

Your available avenues therefore are as follows:
Being a free and open source project, nobody is obligated to provide support unless you're paying them under a support/consulting agreement. But if you can cooperate and play by our rules of engagement, we are more than happy to provide help and answers wherever possible.

Getting the most out of the mapguide-users mailing list

The mapguide-users mailing list should be your first port of call for any MapGuide question or support query. When I get personal emails asking questions about MapGuide or support questions about MapGuide and:
  1. We do not have a pre-existing support/consulting agreement (and if we did, this should've been through my business email, not my personal one).
  2. I find that you haven't posted the question/query to the mapguide-users mailing list first.
  3. The email is not well written or the email is a really basic or pointless question.
I will either tell you to use the mailing list or ignore the email. Simple as that.

Think about it. If you have a question/problem with Windows, do you go and harass Steve Ballmer? If you have a question/problem with Linux, do you go and harass Linus Torvalds? Of course not! You go through the many channels that are available for Windows/Linux, and for MapGuide Open Source that channel is the mapguide-users mailing list, not my personal email address!

I read the mapguide-users mailing list every day. If you ask a MapGuide question on the mailing list, and I have a fair idea of an answer, I will give you one through the mailing list. Don't go emailing me the same question directly afterwards just because nobody has answered your question on the mailing list. I've most likely already seen your question and don't have an answer. Pestering me personally will not change that fact!

I'm not saying these things from a position of arrogance or superiority. The mailing list is not just a forum for support, it's also a knowledgebase, and the only way the mailing list can be an effective knowledgebase is if everybody asks questions and answers through it. When myself or someone gives you an answer through the mailing list, they are not just answering for you, they are also answering for anybody who might have such a similar problem down the line. Pinging myself or any MapGuide user directly instead of through the mailing list is bad etiquette for the following reasons:
  • You're restricting the number of people who could possibly answer your question/query to just myself instead of anyone who's subscribed to the mailing list.
  • You're denying potential answers to anyone who's subscribed to the mailing list who might be having the same problem as you.
It's pretty selfish when you think about it.

However, I do give leeway if the personal emails I get are highly confidential or of the more esoteric type (eg. mg-desktop, MapGuide/Maestro code/architecture/feature discussions) and will happily respond to such queries, but otherwise the above rules apply for the reasons already stated.

Now with that out of the way, here's how you can get the most of the mailing list. The key is to ask good questions. We put this same link on the nabble front-end to the mailing list, but it's apparent that nobody reads that. So since you're reading this blog, read that link before you continue. Seriously!

Now to add some MapGuide-specific context, when you need to ask the question please always specify the following where possible:
  • The version of MapGuide you're using.
  • Your Operating System. For Linux, state your distro.
  • Whether you're running a 32-bit or 64-bit version of MapGuide.
  • Your MapGuide configuration (IIS/Apache, .net/Java/PHP).
  • The version of Maestro you're using (if the question is related to Maestro).
For problems/questions relating to your spatial data, specify which FDO provider you're using. This helps us to better isolate the problem and determine if the problem is specific to MapGuide or the FDO provider.

For problems/questions relating to coding/development, do provide code snippets and explain what you're trying to achieve. Try not to paste your code snippets verbatim in your questions as they're bit ugly to read from the nabble front-end. Consider using something like GitHub gists to put your code snippets in and just link to that gist in your question.

Put screenshots whenever you can. You know the old saying: A picture is worth a thousand words.

Where possible, please try to localize your problem around the Sheboygan sample dataset or publicly accessible WFS/WMS servers. If your problems can be reproduced through the Sheboygan dataset or these WFS/WMS servers, it will make things easier for us to diagnose such problems and there won't be issues of confidentiality around your specific spatial data.

Do become familiar with Firebug and similar debugging tools. For problems relating to the AJAX Viewer or Fusion we'll most likely ask you what Firebug says 80% of the time.

Do keep an eye on what MapGuide is logging. MapGuide may have logged an informative error when your problem occurred.

Understand that the likelihood of getting your MapGuide question/problem resolved decreases with older versions of MapGuide. Simply put, we're not a billion dollar corporation like Autodesk. We simply do not have the resources to support so many different versions of MapGuide. Our default answer is to recommend you upgrade to the latest stable release because:
  • It may have resolved your problem
  • It fits into our "support window" for reproducing these problems. The window will generally be the current stable release and 1-2 versions back.
Please try to avoid general coding/development questions. This is what sites like Stack Overflow were invented for.

Do actually subscribe to the mailing list proper and not just the nabble front-end. If nabble is down or goes away, so will your questions and/or answers.

Finally, we are not psychics who can read your mind. We only know what you're telling us. The more information you give us, the better it is the chances of us being able to diagnose the problem and give you an answer.

Getting the most out of Trac

So your problem is most definitely a defect in the MapGuide product itself or something that requires enhancement work. This is where you probably want to file a ticket. 

Most of what I said about the mailing list equally applies here. So I'll add things specific to Trac.

Don't use Trac for asking questions! This is what the mailing list is for!

When filing defects, include reproduction steps or test code/data that demonstrates the problem. Anything that reduces the setup time in reproducing the problem will get us fixing the problem itself much faster. Again, I'd like to emphasise the importance of being able to localize the defect against the Sheboygan sample dataset. If the defect is reproducible against this dataset, things will be much simpler.

Take ownership of your filed tickets. Don't just file a ticket, leave and then auto-magically expect someone will then fix the problem. Keep these tickets up do date with any important findings and information. If we ask any questions on that ticket, do follow up on our enquiries. A fair chunk of filed tickets are closed due to ticket inactivity because these tickets didn't contain enough information and the submitter failed to add any extra findings or follow-up on questions that we've put on that ticket.

Keep the wiki up to date. Like the mailing list, it's a knowledgebase that benefits everyone.

Having a milestone assigned to your ticket does not guarantee it will be resolved by that milestone. It usually just means that we'll look at the ticket for the release cycle for that particular milestone, and see if we can fix it for that milestone. Once again, more information on the ticket will make this happen. Otherwise, we'll just shelve that ticket for a later milestone, or close it if there is no activity for a certain period of time.

Be specific about enhancement tickets. Don't just file an enhancement ticket stating we wish MapGuide would do XYZ, be specific. If you have an idea about how such an enhancement would be implemented, state your plan of attack.

When submitting patches, understand how to create patches properly. We're happy to accept patches, but it makes it much easier for us if these patches are diffs that can be cleanly applied to a svn working copy. Pay special attention to whitespace (use 4 spaces instead of a tab).

In closing...

Hopefully, this post explained the expectations from you (the user) and from us (the developers/contributors).

Please always go to the mailing list first for any MapGuide questions/support. My personal email address is not for your MapGuide support or basic enquiries!

No comments: