Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
The Gradle Configuration Management Plugins
This wiki is intended for FAQ information, example gradle usage related to standard project management and some discussion topics about the reasoning behind the creation of these plugins.
Detailed usage of the GradleCM plugins can be found in the readme at https://github.com/kercheval/GradleCMPlugin.
There are four main plugins implemented currently to support configuration management. These plugins can be used independently.
The VCS plugin was created as part of the need to detect information about and update the repositories in use to support releases.
All of the other plugins in this of set use the library that support this plugin to accomplish tasks in the system. The exposed methods this plugin supports exposes information and status for the current repository.
Build Info (About) Plugin
The build info plugin support the creation of a properties file which shows information about the build at the time of execution. This file is added to JAR/WAR files by default and can be added to any archive to stamp information about the build.
The information is stored in a standard properties file to simplify programmatic parsing and use. Among other things, the following information is added to file.
- The tasks used in the build
- The current status of the repository in the build system (including modified/added/delete files)
- Build machine information (host info and user info)
- Detected continuous integration build information
- Custom information that you specified in the gradle file to be placed in that file
The version plugin supports a sophisticated pattern based versioning based on tags (by default) that simplify the assignment of the version used for archive publication.
The default pattern follows standard maven practices (major/minor/timestamp), but nearly any usage is supported. Version manipulation methods are exposed to allow setting and incrementing version numbers based on whatever custom criteria you may choose.
This plugin supplies a task to create a tag based on the current version in the repository and branch.
The release plugin supports the creation of release archives and tags based on the current version. This plugin understands the mainline and release branches to ensure correct archive and tagging behavior and will enforce some operations are done only on the release branch.
This plugin is responsible for creating and enforcing the code promotion model described below including the initial creation of the release branch structure, merges from mainline to release and archive publication from release.
Code Promotion Model and Discussion
The GradleCMPlugin was created to support a particular code promotion model. This model is intended for most projects that are organized in a sane manner. In particular the characteristics of the projects should display are as follows:
- Code is organized into appropriate projects and subprojects
- A single release branch is sufficient for project release
- The master branch is used for daily development
- Individual repositories can create release artifacts if necesssary
While the list above seems sort of obvious as what we all want in a VCS, many organizations and lots of open source projects go out of their way to shoot themselves in the foot. Folks dream up all sorts of complicated branching models, complicated ways of maintaining ongoing incremental release code bases and a dizzying collection of environments and deployment structures. While complexity in configuration management is sometimes necessary, it is normally a very expensive waste of time.
Without trying to justify them here, I will state the following as best practices:
- The central repository of your code should contain a single development mainline and a single release branch. This simplifies management and understandability as well as forcing a clean policy for reference. If you are sharing a repository with the world, normally the world does not want to see your experimental, prototype or temporary branches. Display your genius in the release branch, not in complex branching trees.
- Use branches all you want, just do it on your forked or cloned repository. Branches are really for the individual or small groups making modifications over short time periods. If you are working with a group take advantage of forks and remotes to simplify this.
- Try not to use branches for longer running changes, but if you do, merge from the mainline as often as you can and merge back to baseline as frequently as you are able. Logical merge collisions are the hardest to detect and are the biggest source of bugs when using branches. Frequent merges limit this problem.
- For major release or maintenance source, do not use a branch, use a fork named for the release your maintaining. Since you will typically be doing pull requests or direct merges into your mainline repository, don't clutter your principal development lines with maintenance bug fixes. Be wary of maintaining multiple revision repositories at all. Big companies or projects may need to do this for contractual or support reasons, but try to say no. If you must say yes, create a fork for either your mainline or your release, your choice.
- Never embed build logic into your CI build systems. Jenkins, Cruise Control, etc. are great tools for ensuring builds are successful and can be a great help in managing complexity, but embedding critical steps of the build into CI systems limits your abilities to respond to project needs and can lead to big maintenance problems.
Developer vs Central Repository View
This statement should be unnecessary, but your local repository and your central repository will be different. They have different purposes and support different needs.
Normally, your central repository view will look something like this
Your local repository view will normally be much more complex
This reflects the more fluid nature of your local development environment and allows you to focus on creating a workflow that works best for you. The project needs are different than yours and that is completely appropriate. Only the mainline and release branches must look the same between the your repository and the central one that is normally being used for release.
Example Gradle Solutions for Configuration Management and Builds
The example section has concrete examples of how to accomplish some standard tasks for project management