Release cycle he IL

Release cycle

ASF uses common C# versioning which is A.B.C.D. Version is being incremented after releasing current one on GitHub. Every single version released so far is available on GitHub, in frozen state, and will not disappear with time, therefore it's always possible to roll back to any of them, without a need of making self copies.

In general ASF versioning is very simple - we use numbers from 0 to 9 in place of A, B, C and D. Version bump increments D, if new D would result in number 10, we increment C instead and set D back to 0, and so on. Release of a new version is supposed to be treated as ASF milestone, a version with given feature set implemented and ready for tests/usage, while not causing any regressions compared to previous one. Sometimes we may decide that introduced changes are very important and bump C, B or even A instead, although that is quite rare (and usually indicates some breaking changes).

ASF releases are divided into two categories - stable releases and pre-releases.

Stable releases are supposed to be working properly and without any known regressions (at time of release) compared to previous ones. We tend to release stable version either after a longer period of pre-release tests, or as a version that fixes bugs of previous stable release, without introducing new ones. In very rare scenario (e.g. Steam breaking change) we may also decide to release new stable version ASAP, if needed. In general though, those versions should usually work very decent, as we do not mark a version as stable if it results in worse overall health condition compared to previous stable release. Of course, such "overall health" is based on reports and feedback that we're receiving during pre-release development, so sadly it's still possible that some bugs can slip through and will be discovered after stable release, simply because nobody of us ran into it during development phase. Fortunately for us it's pretty rare that something like this happens, and we tend to fix it ASAP in another follow-up stable release.

Pre-releases are more often and usually introduce work-in-progress changes, suggestions or new implementations. Pre-release is not guaranteed to be stable, although we're always trying to do some bare tests before pushing it to GitHub, so it should never be a version that is completely broken in terms of practical usage. The main point of pre-releases is to get feedback from more advanced users and catch newly introduced bugs (if any) before they hit stable release. The quality of that work highly depends on number of testers, bugs being reported on GitHub and general feedback.

Pre-releases should usually work as good as stable releases, and the only difference between those two is simply a fact of being tested by more users. This is because ASF is a rolling project, which means that it should be possible to build and use at any given point of time, and versioning is made for your convenience - as a milestone of changes between one version and another. Still, if you decide to use pre-releases, you should typically be a bit more advanced user, as pre-releases are usually work-in-progress smaller ASF milestones, and it's totally possible that even if something seems to be working decent, it may have stuff that isn't necessarily working or tested yet - tracking ASF development on GitHub and carefully reading changelogs is the minimum that you must do if you want to use pre-releases (for your own good). In addition to that, there are moments when we're actively testing something specific, such as configuration change, new rewritten code for given thing, or core changes. Always read changelog in this case, as such pre-release version could be more unstable than other ones.

Please note that newly introduced features and changes may be undocumented (e.g. on the wiki) until some time later, as documentation is usually written once final code of given feature is ready (to save us time rewriting documentation each time we decide to modify the feature we're currently working on). Due to the fact that pre-release may contain work-in-progress code that doesn't have a final form yet, documentation will arrive at later stage of the development. Same thing applies to general changelog that may be unavailable for given pre-release until some time later. Therefore if you decide to use pre-release then be prepared for looking inside ASF commits from time to time.

Of course, lack of documentation applies only to pre-releases - each stable version must always have complete changelog and documentation on the wiki the moment it's being released.

A pre-release version may be considered stable after some time. This is especially true if there are no changes done in the meantime, and there is no point in version bump just for the sake of stable release. It's also done very often when pre-release is considered "stable release candidate", as it allows advanced users to test it before it gets marked as stable, so the risk of introducing bugs is much lower, therefore this is the most common pattern when it comes to ASF releases:

Stable 1.0 -> Pre 1.1 -> Pre 1.2 -> ... -> Pre 1.7 (RC) -> Stable 1.7 (same as Pre 1.7)

In general though, ASF releases are being released when they're ready, which results in non-predictable release schedule. Usually there is a pre-release at the end of any major feature or change being done, and a stable release if no bugs are found after some time (a few days) since pre-release became available. We're aiming for more or less one stable release per month, unless there are some critical issues to deal with or likewise. Pre-releases are happening on as-needed basis when we feel like there is enough of stuff that needs to be tested since the release of the last one. Depending on how busy ASF development is in given moment, this can be from a few to a dozen of pre-releases between each stable release.

The precise changelog that compares one version to another is always available on GitHub - through commits and code changes. In release we tend to document only changes we consider important between last stable and current release. Such brief changelog is never a complete one, so if you'd like to see every change that happened between one version and another - please use GitHub for that.

ASF project is powered by continuous integration process and tested by two independent services - AppVeyor which tests ASF on Windows, and Travis which tests ASF on Linux and OS X. Every build is supposed to be reproducible, therefore it should not be a problem to grab source (included in release) of given version and compile yourself receiving the same result as the one available through a binary.

As an extra, in addition to ASF stable releases and pre-releases, you can also find latest automated AppVeyor build here which is typically built from latest not-yet-included-anywhere commit. Due to automation and lack of any tests, those builds are NOT supported in any way, and typically are available only for developers that need to grab most recent ASF GitHub snapshot in object form, so they won't need to compile themselves. Nothing guarantees that ASF in master state will work properly. In rare cases, those builds can also be used for verifying if given not-yet-released commit indeed fixed particular issue or bug, without waiting for the change to land in pre-release. If you decide to use those automated builds, please ensure that you have decent knowledge in terms of ASF, as it's the highest "level" of bugged software. Unless you have a strong reason, usually you're already on the bleeding edge by tracking pre-release builds - AppVeyor builds are offered as an extra to pre-releases, mainly for verifying if given commit fixed particular issue we're working on right now. Those builds should not be used in any production environment.