Announcement: Bitbucket Server 6.0 Early Access Program (EAP) release

bitbucket-server
eap
announcement

#1

Hi everyone,

We are pleased to announce the availability of the first Early Access Program (EAP) release of Bitbucket Server 6.0.

This EAP release is so that plugin vendors and customers who have written in-house plugin can update their plugin to ensure they will work with the public release of Bitbucket Server 6.0.

Important things to note about this EAP release:

  • This release should not be used in a production environment .
  • There may be other minor API changes between this release and the public release of Bitbucket Server 6.0.

Obtaining the Bitbucket Server 6.0 EAP release

Links to download installers and archives:

Sources are available for users with a valid Bitbucket Server license through their license details at my.atlassian.com.

The Bitbucket Server 6.0 EAP can also be run with AMPS version 6.3 or later by running this command with the Atlassian Plugin SDK installed:

atlas-run-standalone -u 6.3.21 --product bitbucket --version 6.0.0-eap1

Note that if Atlassian Plugin SDK version 6.3 is installed, the “-u 6.3.21” parameter can be omitted. The atlas-version command can be used to determine the installed version.

We need your feedback!

If you have any questions or feedback about this preview of Bitbucket Server 6.0, ask them in the Bitbucket Server category here in the Atlassian Developer Community forums, and our friendly team of developers will respond to them.

Bitbucket Server 6.0 EAP Release Notes

Bitbucket Server 6.0 EAP contains several changes that may affect existing add-ons. The changes are summarised below.

Deprecated Java APIs removed

Interfaces, classes, and methods in the Bitbucket Server Java API that were previously marked as deprecated have been removed.

Plugins that use any of these interfaces (which would have generated deprecation warnings when built against Bitbucket Server 5.x) generally won’t build with Bitbucket Server 6.x

Precompiled plugins that used any of the removed interfaces will fail to install or run in Bitbucket Server 6.x, typically with java.lang.NoSuchMethodError or java.lang.ClassNotFoundExceptions.

Removal of the legacy Repository Hooks API

Bitbucket Server 5.0 introduced a new Repository Hooks and Merge Checks API. In 6.0 the legacy API has been removed. For an overview of the new API please see the Repository Hooks and Merge Checks Guide.

Removal of direct access to repositories on disk

In Bitbucket Server 5.10 direct access to our repositories on disk for plugins was deprecated. In 6.0 the deprecated API that permitted this has been removed. For further information please refer to the Bitbucket Server API Changelog entry for 5.10.

Removal of other deprecated API

Please refer to the Bitbucket Server 5.16 Javadoc for finding replacements for other deprecated/removed API:

Removal of provided Scala runtime

Plugins written in Scala were able to depend on Bitbucket Server (in versions older than 6.0) to provide the Scala runtime library (org.scala-lang:scala-library) as as such did not need to bundle it in the plugin. As of Bitbucket Server 6.0 Bitbucket Server does not provide/export this dependency.

Java 11 support

Bitbucket Server 6.0 adds support for running on a Java 11 JRE, in addition to retaining support for Java 8. Plugins should be build with a target version of Java 8 which implies a language level of Java 8 also. Plugins must be tested on both Java 8 and 11.

Note: Java 11.0.2 is unsupported due to Java bug JDK-8217364.

AUI 8 upgrade

Bitbucket Server 6.0 upgrades Atlassian User Interface (AUI) from 7.x to 8.0 For more information on upgrading to AUI 8 see the AUI 8 upgrade guide.

Internal Web Resources blocked

Though they were never API, some plugins have depended on web-resources in the plugin com.atlassian.bitbucket.server.bitbucket-web. In 6.0, most of the dependencies will stop working. Please use an equivalent public API, if available. Some exceptions were made for heavily used resources, but these will eventually be replaced with supportable implementations of API and will also be removed in the future.

The temporary exceptions are:

  • :server-soy-templates
  • :global
  • :require-lite
  • :revision-reference-selector
  • :pull-request-can-merge
  • :events
  • :dom-event-util
  • :user-multi-selector
  • :group-multi-selector
  • :time
  • :global-repository-selector
  • :avatar-picker-dialog
  • :branch-multi-selector
  • :searchable-multi-selector

Internal JS/AMD modules blocked

Similar to the above, some internal AMD modules were depended on by plugins. In 6.0, third-party plugins that depend on modules starting with bitbucket/internal/ will stop working. Where an equivalent public API is available, use that. Otherwise, consider implementing your own version of the functionality. Some exceptions were made for heavily used modules, but these will eventually be replaced with supportable implementations of API and will also be removed in the future.

The temporary exceptions are:

  • bitbucket/internal/feature/pull-request/can-merge/can-merge
  • bitbucket/internal/feature/repository/branch-multi-selector/branch-multi-selector
  • bitbucket/internal/feature/repository/global-repository-selector/global-repository-selector
  • bitbucket/internal/feature/repository/revision-reference-selector/revision-reference-selector
  • bitbucket/internal/feature/user/group-multi-selector/group-multi-selector
  • bitbucket/internal/feature/user/user-multi-selector/user-multi-selector
  • bitbucket/internal/util/dom-event
  • bitbucket/internal/util/events
  • bitbucket/internal/util/time
  • bitbucket/internal/widget/avatar-picker-dialog/avatar-picker-dialog
  • bitbucket/internal/widget/searchable-multi-selector/searchable-multi-selector

Internal JS events not supported

Events (consumed using bitbucket/util/events) starting with bitbucket.internal have never been official API but will no longer be able to be subscribed to and should not be considered stable or part of any official API.

TextView API no longer supported

As a result of the changes to internal JS events and other changes, the TextView API (which was only accessibly via an internal event) will no longer be accessible or supported. The TextView API was for modifying the source or diff view. Where possible it is suggested to use Code Insights to display extra information on a diff. Key methods of the TextView API were addLineClass, addLineWidget, and registerGutter/setGutterMarker.

Custom file-handlers no longer supported for diff views

Custom file-handlers are no longer supported for diff views (but continue to be supported for source views). Any custom file-handlers registered for diff-views will be ignored when resolving the appropriate handler.

Removed support for previously supported platforms

  • Support for the following database versions has been removed:
    • Postgres 9.2
    • Postgres 9.3
  • Support for running Bitbucket Server with (server side) Git versions older than 2.11 has been removed.
  • Support for ElasticSearch 2.x has been removed

These changes should not impact the development or running of third-party plugins.

Java platform update

Bitbucket, along with most Atlassian Server and Data Centre products, provide a standard set of libraries and plugins for which API is stable for a given major release. These are known as the platform. In Bitbucket Server 6.0 these have been updated, with many including major version updates.

3rd Party

Module Version
Spring Framework 5.1.3.RELEASE
BND 3.5.0
Apache Felix 5.6.10
Guava 26.0-jre
com.google.code.findbugs:jsr305 3.0.2
SLF4J 1.7.25
javax.activation 1.2.0
javax.annotation 1.3.2
javax.servlet-api 3.1.0
javax.ws.rs-api 2.0.1
javax.validation:validation-api 2.0.1.Final
commons-lang 3.8.1
commons-fileupload 1.3.3
commons-io 2.6
Apache HttpClient 4.5.5
Apache HttpCore 4.4.10

Atlassian Modules

Module Version
atlassian-plugins 5.0.0
atlassian-event 4.0.0
activeobjects 3.0.0
activeobjects-plugin 3.0.0
atlassian-rest 6.0.0
atlassian-refapp 5.0.0
atlassian-scheduler 3.0.0
atlassian-oauth 4.0.1
atlassian-trusted-apps 5.0.0
atlassian-sal 4.0.0
atlassian-cache 4.0.0
atlassian-soy-templates 5.0.0
atlassian-nav-links 5.0.0
atlassian-template-renderer 4.0.0
quickreload 3.0.0
atlassian-plugins-webfragment 5.0.0
atlassian-plugins-webresource 4.0.0
atlassian-plugins-jquery 2.2.4.6
beehive 2.0.0
velocity-htmlsafe 3.0.0
application-links 6.0.1
less-transformer-plugin 4.0.0
atlassian-util-concurrent (see note below) 4.0.1
fugue (see note below) 4.7.2
atlassian-httpclient 2.0.0
atlassian-http 2.0.2
atlassian-webhooks-plugin 6.0.0
atlassian-failure-cache 2.0.0
atlassian-annotations 2.1.0
atlassian-pretty-urls 3.0.0
atlassian-healthcheck 6.0.0
atlassian-instrumentation 3.0.0
atlassian-spring-scanner 2.1.7
atlassian-marshalling-api 1.0.0

atlassian-concurrent-util: Note the package name has also changed from com.atlassian.util.concurrent to io.atlassian.util.concurrent. In order to ensure a smooth transition the old package is still exported and will continue to be until Bitbucket Server 7.0 is released.

fugue: Note the package name has also changed from com.atlassian.fugue to io.atlassian.fugue. In order to ensure a smooth transition the old package is still exported and will continue to be until Bitbucket Server 7.0 is released.


Bitbucket Server 6 EAP?
#2

Great, but Elasticsearch won’t start automatically, mistake in /opt/atlassian/bitbucket/elasticsearch/bin/elasticsearch-env file
Line 91 must be:
ES_TMPDIR=mktemp -d -t elasticsearch.XXXXXXXX

(omitted .XXXXXXXX in original file)


#3

#4

Hi @apytlev,
Thanks for reporting the issue. This is a bug in the elasticsearch startup script, the current workaround is to set ES_TMPDIR before starting Elasticsearch. We have updated Bitbucket’s startup scripts to set ES_TMPDIR before starting Elasticsearch. This should be available in the 6.0 final release.

Cheers,
Justin


#5

Dear Atlassian team!

Thank you for sharing the EAP release.

We are StiltSoft, Top Platinum Vendor, developers of Awesome Graphs for Bitbucket Server.

Your internal JS API is great, and our app heavily depends on it.
We kindly ask you to make some modules a part of your public API and temporary not to remove them:

  • bitbucket/internal/widget/paged-table

  • bitbucket/internal/widget/searchable-selector

  • bitbucket/internal/widget/delete-dialog

  • bitbucket/internal/widget/searchable-multi-selector

  • bitbucket/internal/util/history

  • bitbucket/internal/util/client-storage

  • bitbucket/internal/util/navigator

  • bitbucket/internal/util/notifications

  • bitbucket/internal/util/shortcuts

  • bitbucket/internal/feature/alerts/alerts

  • bitbucket/internal/feature/commits/commits-table

  • bitbucket/internal/feature/repository/revision-reference-selector

  • bitbucket/internal/feature/repository/global-repository-selector

  • bitbucket/internal/feature/user/user-multi-selector

  • bitbucket/internal/model/revision-reference

  • bitbucket/internal/model/repository

  • bitbucket/internal/page/commits

  • bitbucket/internal/impl/urls

  • bitbucket/internal/bbui/pull-request-list-table/pull-request-list-table

  • bitbucket/internal/bbui/pull-request-list-table/pull-request-list-table/components/summary


#6

Hi @plukyanenko,
Thanks for the feedback. We’ll be discussing internal modules in the coming week, so while I can’t give you any definitive answers now, I can say we will be looking into it and hope to get back to you soon.
Cheers,
Mark


#7

Hi there, @plukyanenko

Note that your app shouldn’t be depending on those, as they aren’t API and can change in any release (and have already changed many times in the past). We’ve acknowledged that many apps are using our internal modules and so we made exceptions for modules that we’ll leave around for the time being. Note that some of the ones on your list are already exempted, but that the module names changed many releases ago and the deprecated names have simply been removed in 6.0. So you’ll need to update to the new module name listed in the temporary exceptions above, but otherwise things are generally unchanged. user-multi-selector, revision-reference-selector, etc are examples of this.

Some modules we can keep around and eventually release API versions that we are happy supporting formally. For example most of our visual components are a mix of Soy and JS that we don’t feel comfortable supporting, but we could in the future release a Web Component version that is supportable. Some might also be better provided by AUI or AtlasKit. For example, warning dialogs are a standard AUI component and you can build a delete-dialog from that.

Some we definitely will not support. For example bitbucket/internal/page/commits exports an onReady function and is not meant to be reused in any way. I don’t know how you’re using it, but perhaps you should instead link or redirect to the built-in commits page?

Consider reimplementing the functionality of any modules we’ve not created exceptions for.

Here’s what I’m expecting to do now. Because we could conceivably expose an API version of them in the future, I will add temporary exceptions for the following internal modules to tide you over until we do:

  • bitbucket/internal/util/client-storage

    • this handles LRU invalidation which is a nice thing to expose for plugins, and allows caching per user/project/repo. We could likely support a public API for this.
  • bitbucket/internal/feature/alerts/alerts

    • We currently have a web-panel location at bitbucket.notification.banner.header for these kinds of alerts. That should work for you. However, I understand this banner UI is outdated, and our own web-panels at that location simply call the alert.add() method you are presumably using. We should expose a public API for this, so I’ll leave the existing module intact in the meantime.
  • UI components:

    • We don’t have these implemented in a way that we can cleanly support (e.g. they are legacy JS and Soy, or would tie us to a React version. Web Components wouldn’t have these issues). So I will expose these implementations in the meantime, unsupported, and the ultimate path forward will be to release public API components that plugin devs can rely on instead of these.
      • bitbucket/internal/feature/commits/commits-table
      • bitbucket/internal/bbui/pull-request-list-table/pull-request-list-table
      • bitbucket/internal/bbui/pull-request-list-table/pull-request-list-table/components/summary

I will NOT add exceptions for these modules because I don’t believe we can/should support them long-term. However, if you tell me more about how you’re using them, perhaps I can help you find a workaround for them (I’ve tried to list some already):

  • bitbucket/internal/widget/paged-table
    • internally we are moving toward React UIs where this module will be obsolete. Please implement your own paging.
  • bitbucket/internal/widget/delete-dialog
    • you can build your own from AUI dialog2 warning dialogs. It’s better for AUI to own generic components.
  • bitbucket/internal/impl/urls
    • Use the supported bitbucket/util/navbuilder module for any URL munging
  • bitbucket/internal/page/commits
    • this module simply exposes an onReady method for use by our /commits page. Perhaps redirect to that page instead.
  • bitbucket/internal/model/revision-reference
    • We’re moving away from use of these model objects to plain JSON. You can get JSON shapes from the public API bitbucket/util/state. The minimal logic in here should be reimplemented if you need it. I’ve noticed that revision-reference-selector requires one for setSelectedItem. If you needed revision-reference to be able to call that method, then here’s a workaround. Since you’re already using an internal component, I’d suggest comparing your ref to selector._selectedItem and if they are different, calling selector._itemSelected with JSON instead of a RevisionReference.
  • bitbucket/internal/model/repository
    • see revision-reference above. The workaround won’t work if you need to pass in a Repository to revision-reference-selector, but I’m hoping you don’t? The workaround will work for repository-selectors.
  • bitbucket/internal/widget/searchable-selector
    • This is another generic component that is better suited to being an API from AUI or AtlasKit. I’d be interested in what kind of items you are rendering, but would prefer to expose selectors that are specific to a Bitbucket business object.
  • bitbucket/internal/util/history
    • This is mostly just a wrapper around the native browser History API, and it’d be better if you relied on that directly. It also exposes events when pushState() is called, but I would hope that plugins don’t have to rely on generic events for that (as our plugin platform changes, I’m not sure we could always fire it at the right time or with the right information). Is there a specific kind of page transition you need to listen for? Perhaps we can expose something more specific for your use case.
  • bitbucket/internal/util/navigator
    • I’d rather not encourage browser sniffing in plugins (it would be nice to remove our own. Also the logic for this is relatively simple. I’d suggest reimplementing the part of this you actually need.
  • bitbucket/internal/util/notifications
    • This is a small wrapper around AUI flags that adds “flash” notifications across page loads. That feels like it could be a nice enhancement for AUI’s APIs more than Bitbucket Server’s. Is there a specific case where you need to add a flash notification that shows on one of our pages? If not, please reimplement this with AUI flags.
  • bitbucket/internal/util/shortcuts
    • We have our own little conventions for how to make a keyboard shortcut, but it’s not something you need to implement for your own keyboard shortcuts. There’s probably a lot of stuff in there you don’t need anyway. I’d suggest just directly hooking to your . Alternatively, if you’re trying to override one of our keyboard shortcuts, please let me know why and perhaps I can offer a workaround.

I will NOT add exceptions for these modules because I believe you can simply use the new module name:

  • bitbucket/internal/widget/searchable-multi-selector
  • bitbucket/internal/feature/repository/revision-reference-selector
  • bitbucket/internal/feature/repository/global-repository-selector
  • bitbucket/internal/feature/user/user-multi-selector

Hope that clarifies things! Please let me know if you have any questions or other info to share. The goal is for us to move toward a clean separation of internal and API modules that we’ll enforce more and more over time. Some effort will be required by plugins in major releases to help us get there, but we’ll try to give you a path forward.

Cheers,
Adam


#8

Hi @aahmed

Thank you for so detailed answer.

Let me explain why we so actively use the internal API of Bitbucket instead of writing own code:

  • We want to provide users with maximally native user experience. Ideally users should not distinguish whether they use a native feature of Bitbucket or a feature of our app.
  • We don’t want to write, test, support code which duplicates functionality of Bitbucket.
  • We don’t want to track changes in behaviour of Bitbucket UI, and adapt to them our code duplicating Bitbucket’s features.

Here are two examples of how we use internal API.

Example 1

Our app shows the commit graph with all branches together.

To implement this feature we need that the standard component bitbucket/internal/feature/commits/commits-table
gets data from our API

For this purpose we redefine the method buildUrl in this way

define('page/awesome-commit-graph-table',
    ['jquery', 'graph/navbuilder', 'bitbucket/internal/feature/commits/commits-table'],
    function ($, nav, CommitTable) {

        'use strict';

        function GraphsCommitsTable() {
            CommitTable.apply(this, arguments);
        }

        $.extend(GraphsCommitsTable.prototype, CommitTable.prototype);

        GraphsCommitsTable.prototype.buildUrl = function (start, limit) {
            return nav.commitsGraph().withParams({start: start, limit: limit}).build()
        };

        return GraphsCommitsTable;
    });

Then while loading the page we replace the standard realisation by ours.

requirejs.config({
            map: {
                'bitbucket/internal/page/commits': {
                    'bitbucket/internal/feature/commits/commits-table': 'page/awesome-commit-graph-table'
                }
            }
        });

#9

Example 2

bitbucket/internal/widget/searchable-selector is used to show the selector of committers on one of our graphs


#10

Good to know - thanks for the details.

Please do note that this is very much not supported and your commit graph could break in any release. If this functionality is essential, I’d recommend finding a way to inject your graph without touching any of the existing code on that page. E.g. create a div next to the table that you populate with the graph. You can either use a second REST request to get data or you can add a at bitbucket.commits.extras with a web-panel at my-key (or whatever you use for the section key). This will add a column to the table, which you can style to be 0 width, but the web-panel will get information about each commit, which you can then use to render your graph. You can use the web-panel being rendered to trigger an update of the graph too (e.g. by rendering , then updateGraph would use debounce() so that even though a page of commits calls it 25 times - once per commit, the graph is rendered once with all 25). This isn’t the prettiest code, but it should be more robust since you’ll be using supported APIs. The div you add could still be broken since our DOM isn’t API either. But at least the unsupported surface area is lower.


#11

Would user-multi-selector work here? Or do people mostly only search for themselves? Could a toggle for “Only my commits” work?