Migration from Globals to AMD
Though not all of the code in Jira front-end is a formal or official API, we understand that Jira’s history has been to create global variables that can be re-used by plugin code.
The plan of the Jira development team is to eventually convert all global objects to AMD modules, and for all the front-end code dependencies to be explicitly declared in the code rather than configuration.
Part of the development team efforts to convert modules is also to ensure that functions or objects important for plugins are exposed and documented as the proper and supported API.
This effort has been there for a long time already (50% Jira Core JS accessible as AMD modules since Jira 6.2; 100% since 7.2). There are no official dates however as of 8.0 we consider the usage of all JS globals as deprecated and may gradually remove certain global objects provided there’s an alternative AMD module already available.
What’s new in 8.0
As of Jira 8.0 we are (strictly) deprecating usage of JS Global Variables in Jira.
What does “Deprecated” mean
Deprecation is the discouragement of use of some terminology, feature, design, or practice, typically because it has been superseded or is no longer considered efficient or safe, without completely removing it or prohibiting its use. It can also imply that a feature, design, or practice will be removed or discontinued entirely in the future.
Why are we removing global variables
The globals are what’s holding back some significant performance gains in Jira (amongst others gains like stability, reliability, predictability, or maintainability). Performance has been and will be our major focus in the foreseeable future.
High level plan for removing global variables
The team has been preparing a new, official and supported, solution to replace global variables, which is AMD modules. This solution is, to a large extent, already implemented in the Jira codebase. The full coverage will be achieved by creating the missing AMD modules over time. To provide you with some context - 50% of Jira’s core JS code has been AMD + globals since Jira 6.2, and 100% AMD + globals since 7.2. The AMD modules are “stable” and work.
As we're proceeding with converting global variables into AMD modules, we’re leaving the global variables intact so that everything is backward-compatible and they still work for some time.
Global variables that provide support for specific functionality will be removed only when an alternative solution for that piece of functionality is in place, and with proper notice beforehand.
AMD modules will be supported by documentation and upgrade guides. We’re planning to use the new solution fully in Jira 9.0.
Long term impact
The team might decide to keep all global variables in Jira 8.0 but gradually remove them in 8.x, again - with proper notice beforehand.
It means that global variables may stop working completely in Jira 9.0.
How should I prepare?
As of 8.0:
All Globals are considered deprecated and should not be used.
All possible usage of globals is considered as deprecated and developers should have a plan to move to alternative solutions (AMD modules).
Ideally, they should incorporate the alternative solution. In practice, in most use case scenarios, this will work for our current enterprise releases as we practically have not introduced any new AMD Modules in the meantime.
AMD Modules must be used for any newly built plugin code, unless the required AMD module does not exist, yet.
In such case plugin vendors may use existing global, though they should migrate to an AMD module as soon as it becomes available in Jira.
We have 100% coverage of globals → AMD modules space in Jira Core, and we will increase the coverage in Jira Software until 100% of data accessible via globals becomes available trough AMD modules.
*should,may,must as per https://www.ietf.org/rfc/rfc2119.txt.
Post 8.0 release:
We will disable support for globals, which have AMD modules available for years already (since 6.x or early 7.x).
We will do it on a case-by-case basis and will document the migration (exact list of deleted globals and their AMD module name equivalent).
Moreover, we will introduce new AMD modules to cover all the globals in Jira Software that don't yet have any alternative. We will do it on a case-by-case basis and document the migration (exact list of deprecated globals and their AMD module name equivalent).
We will start doing so as of 8.x.
Definition of API
We cannot promise that in the future all AMD modules will be a part of the API but currently there’s 1-1 mapping between converted global variables and the corresponding AMD modules so the access to the JS objects remains the same, and only the method is changing.
Upgrade documentation
Currently, we do not provide documentation for the new solution. It also means that we will not be removing any global variables, for now…
Once we decide to remove a particular subset of globals in Jira 8.x, we will provide a detailed migration documentation, containing removed globals list and their AMD module names equivalents.
This documentation will be released alongside EAP for the upcoming release so that everyone can prepare for the changes.