-
Notifications
You must be signed in to change notification settings - Fork 314
Ci server and release process requirements
The CI server should be invoked based on pushes to different git branches. The branch we push to indicates our intent:
- development - This is our first pass run of CI. Just build all the targets. This is the branch for bringing in big features.
- hotfix - This is the branch for minor changes and bug fixes.
- staging - This is the pre-release branch. In addition to running everything that master does it also runs tests, generates documentation and builds the binary SDK.
- publish - Pushing to this branch starts the full release process, which does everything staging does but, if everything succeeds, also publishes the binary SDK and online documentation, merges to the stable and hotfix branches and creates a tag in each indicating the major/minor release.
- stable - This is just a branch to hold a 'clean' history of releases. Doesn't trigger any CI.
Developers can push to either development or hotfix to kick off the baseline CI. The intent is for hotfix to be minor changes and bugfixes and for development to be major changes and features.
We don't really care if github or gitflow is being used as long as everything winds up in development at the end of the day.
The community will submit hotfixes to master via pull request, which someone internally will merge in then bring over to hotfix. If someone submits a larger change or feature to master, we'll ask them to re-submit directly to development, in which case the author of the submission must fix any conflicts so that the pull request can be one-click accepted.
When we're ready to do a release, we'll do a pull request from development or hotfix into staging. If we're happy with the result, we'll then push to publish.
Any developer with push access to the repository may prepare a release.
Our release products are the binary SDK(s) and the online documentation. There are two versions of these: those from staging and those from publish/stable. For the online docs there should be two copies: one for the staging/development product and one for the stable product.
Our SDK version number consists of three parts: major, minor and revision. In addition there are three flavors of the SDK: 'developer', 'staging' and 'stable'. Only the 'staging' and 'stable' flavors have a revision number. All of these are held in a header file. There should be a default version header in src/config-default and a local copy in src/config.
The major/minor version number are updated manually (in src/config-default) on an as-needed basis. Not every release will change these numbers.
When a developer builds an ad hoc Moai executable, the developer's local copy of the version header is used. The default version of this header will not have a revision number and will report the developer name as 'unknown.' Each developer should make a local copy of this header and provide their name.
The CI server will also have its own local copy of the version header so it can auto-increment the revision number and set the appropriate flavor. The staging and release versions of the SDK will each have their own revision counter. The revision counter should reset if the major/minor version number changes.
Examples:
- Moai SDK 1.7 (ad hoc build by Patrick Meehan)
- Moai SDK 1.7 revision 12 (staging)
- Moai SDK 1.7 revision 2
Historically there's only been one binary SDK. Moving forward we should prepare a binary SDK for each supported development platform. The binary SDK should contain:
- Binaries for every library, both Moai and 3rd party, build for the target platform.
- Binaries for all of the standard hosts for the platform.
- Header files for Moai and the 3rd party libraries.
- Source code for the target platform hosts.
- Example IDE projects that build the hosts linked against the static libraries.
- Example IDE projects that show how to extend Moai through additional static libraries.
- A copy of the complete offline SDK documentation.
Possible flavors of the binary SDK:
- Windows - Desktop, Android, NaCl; Visual Studio (Desktop) and cmake (Android, NaCl)
- OSX - Desktop, iOS, Android, NaCl; Xcode (Desktop, iOS) and cmake (Android, NaCl)
Linux developers can use cmake to build for desktop, Android or NaCl.
As of this writing, the example IDE projects live in their own directory structure and are annoying to update. They are easy to forget about and it's unclear if they are currently part of CI. Moving forward we should restructure the main project to make sure these example IDE projects live alongside our development IDE projects and are also known to CI. We should also find an easier way for external developers to add their own extensions to the host without having to edit the host source. We can do this by using header file fallbacks - provide a default registration header that the developer can copy and add their own AKU* initialization calls to.
Ideally the example IDE projects and source that gets shipped with the binary SDKs will mirror the structure of our development project, just with certain folders, projects and sources missing. For example, under the vs2008 folder, the example IDE solution and projects should exist alongside the development versions. They will draw from the 'bin' folder. To make a binary release we'll simply remove the development solutions and projects and leave the release versions with their relative paths in place.
The Lua SDK documentation is currently generated via a multi-pass process that involves doxygen, perl and a custom parser written using Moai's built-in parser. For each source file doxygen is first used to produce a default html output. This is then transformed, first by perl and then by the Moai parser to format the html based on Moai/Lua specific keywords.
The current process works, but isn't ideal. First, doxygen has no easy way to differentiate between a Lua SDK documentation comment and a C++ API documentation comment. This means that, for now, there is no C++ API documentation. The process is also complicated and frail in that it is very version-dependent on doxygen and the two additional parsers.
Ideally, there will be just one (non-perl) parser that handles the transform from doxygen html to Lua SDK html.
We should also look at ways to isolate the Lua SDK documentation in a way that also allows traditional doxygen comments for the C++ API.
When a new binary SDK is published, the build server should download it from getmoai.com, unpack it and build every target.