Guidelines for writing good forum posts


(Gradle FAQ Bot) #1

The Gradle Forums are the primary support channel for the Gradle community. Users and developers of Gradle regularly monitor the forums, donating their time to solve problems and answer questions. To help everyone get the most out of the forums, here are some tips and guidelines for good posts that will increase the chance of someone taking the time to help with your question or problem and get to a resolution faster.

This is a living document. If you have suggestions for additions of modification to this content, please leave a reply or comment below.

All topic types

Be polite and put some effort in

Posts that are written politely are much more likely to get responses. People are also less likely to take the time to respond to posts where the poster has not put the time in to write a good post.

It’s also polite to use correct spelling and grammar (if you can, English is not everybody’s first language) as it makes reading the post easier.

Use meaningful, specific subject lines

This is the first bit of information that is visible by other users when receiving email notifications and browsing the forums. Try to include enough information to summarise the post accurately yet succinctly. The subject line should be clear enough about the topic to grab the attention of people who may know the answer.

The following are examples of bad subjects:

  • Should this work? * Problem with plugin X * How can I do this… * X broken

None of theses subjects convey what they are about. Here are some good examples:

  • I am getting a java.lang.ClassCastException on an imported Ant build when upgrading to milestone6. * Is there any way to override an extension property from gradle.properties? * How can I use uploadArchives without the Java plugin?

Include code samples, context, be clear and concise

  • Try to minimise the code to the smallest possible sample that illustrates the problem * Use <code> tags for improved readability

Provide environment info

You should always provide the Gradle version that you are using. Gradle is evolving continuously and internals can change across releases. It might be best if you simply include the output of ‘gradle -v’ which also includes other important environmental factors like OS (particularly if you are on Windows) or the Java Version.

Problems

Problem topics should be used when something is not working as expected or produces some kind of an error. If you are having difficulty working out how to do something, please post it as a question.

The most important thing is to accurately describe the symptom of the problem. Here are some things to consider to help:

  • Include error messages and stacktraces if possible * If encountering unexpected behaviour; clearly describe steps to reproduce, the inputs, expected behaviour and actual behaviour * Include code/build script sample using <code> tags and keep it to minimum required to demonstrate the problem.

Avoid discussing what the cause of the problem might be unless the symptoms are clearly explained. That is far more valuable information.

Questions

Question topics should be used when seeking clarification on how something should be done. If something is not working as expected and you believe it to be in error, please post it as a problem.

If you are asking how to do something, it’s a good idea to include why you want to do it. Including the why may lead to a new idea that is better and also often makes it easier to give the how.

Be sure to check the documentation before asking your question. If possible, indicate where you looked for the answer to your question so the documentation can be improved.

Ideas

Idea topics should be used when proposing new features or improvements.

When posting ideas, be sure to include how you would use the idea. It can be hard to grasp the context of an idea just on a description of the feature or improvement.

It’s usually a good idea to focus on how a feature or improvement might be used instead of how it might be implemented.