How to update your add-on
How to update your app
The app key of your plugin must not change
The value of your app key, as defined within the atlassian-plugin.xml file, must not change. This is often defined in terms of the maven groupId and artefactId of your plugin. This value is used by Atlassian Marketplace and other parts of Bitbucket Data Center as a unique identifier for your plugin. Changing this value could lead to data loss, and will cause you to lose review and download history on the Atlassian Marketplace.
For example, you would replace the variables below with the values for groupId and artifactId in your pom.xml.
<atlassian-plugin key="${project.groupId}.${project.artifactId}" ...
Update your pom.xml file to reference the latest version of the Bitbucket Server 4.0. You will need to update version properties for both Bitbucket Server and AMPS, which currently requires a pre-release version to build Bitbucket Server plugins, as well as dependencies on any API artifacts.
<dependency> <groupId>com.atlassian.bitbucket.server</groupId> <artifactId>bitbucket-api</artifactId> <version>${bitbucket.version}</version> <scope>provided</scope> </dependency> ... <properties> <bitbucket.version>4.0.0</bitbucket.version> <bitbucket.data.version>${bitbucket.version}</bitbucket.data.version> <amps.version>6.1.0</amps.version> ... </properties>
In your pom.xml you will also need to change or add configuration for the
bitbucket-maven-plugin
(depending on whether you are supporting both Stash and Bitbucket Server, or just Bitbucket Server):<build> <plugins> <plugin> <groupId>com.atlassian.maven.plugins</groupId> <artifactId>bitbucket-maven-plugin</artifactId> <version>${amps.version}</version> <extensions>true</extensions> <configuration> <products> <product> <id>bitbucket</id> <instanceId>bitbucket</instanceId> <version>${bitbucket.version}</version> <dataVersion>${bitbucket.data.version}</dataVersion> </product> </products> </configuration> </plugin> </plugins> </build>
Update your app name and description in pom.xml to reference "Bitbucket" instead of "Stash". For example:
<name>Bitbucket Server - Realtime Editor</name> <description>Provides support for real-time collaborative editing.</description>
Optional: If your plugin will only support Bitbucket Server, remove any Stash dependencies
<groupId>com.atlassian.stash</groupId> <artifactId>stash-api</artifactId>
- For a class with compilation errors, first remove any
com.atlassian.stash
import statements that are red. - Use the suggested imports your IDE provides, and/or consult the API Changelog and table below.
- Open the
atlassian-plugin.xml
inside your IDE- Rename any
com.atlassian.stash
imported components tocom.atlassian.bitbucket
(or equivalent as mentioned in the API changelog) - If you are using any web-resources with a dependency on
com.atlassian.stash.stash-web-api
, change them tocom.atlassian.bitbucket.server.bitbucket-web-api
- Check for any other changes in your resources required due to renamed frontend API
- Rename any
If your app has JavaScript which uses the Stash JavaScript API, change your AMD module imports from
stash/api/*
tobitbucket/*
Test the app starts in Bitbucket Server using:
mvn clean bitbucket:debug
Other helpful resources
- Bitbucket Server developer documentation.
- Ask a question on Atlassian Answers, using the "bitbucket-server" topic.
- Review the End of support announcements to ensure that you're aware of updates to this policy.
Outline of API changes
Java packages
Stash 3.x
com.atlassian.stash
Bitbucket 4.x
com.atlassian.bitbucket
App Key (in atlassian-plugin.xml)
Stash 3.x
<atlassian-plugin key="${project.groupId}.${project.artifactId}" ...>
または
<atlassian-plugin key="com.myorg.stash.awesome-plugin" ...>
Bitbucket 4.x
<atlassian-plugin key="com.myorg.stash.awesome-plugin" ...>
(must not change in either case)
<atlassian-plugin key="com.myorg.stash.awesome-plugin" ...>
Maven plugin
Stash 3.x
<artifactId>maven-stash-plugin</artifactId>
e.g.
<plugin>
<groupId>com.atlassian.maven.plugins</groupId>
<artifactId>maven-stash-plugin</artifactId>
<version>${amps.version}</version>
<extensions>true</extensions>
<configuration>
<products>
<product>
<id>stash</id>
<instanceId>stash</instanceId>
<version>${stash.version}</version>
<dataVersion>${stash.data.version}</dataVersion>
</product>
</products>
</configuration>
</plugin>
Bitbucket 4.x
<artifactId>bitbucket-maven-plugin</artifactId>
e.g.
<plugin>
<groupId>com.atlassian.maven.plugins</groupId>
<artifactId>bitbucket-maven-plugin</artifactId>
<version>6.1.0</version>
<extensions>true</extensions>
<configuration>
<products>
<product>
<id>bitbucket</id>
<instanceId>bitbucket</instanceId>
<version>${bitbucket.version}</version>
<dataVersion>${bitbucket.version}</dataVersion>
</product>
</products>
</configuration>
</plugin>
Exceptions
Stash 3.x
com.atlassian.stash.exception.ServiceException
Bitbucket 4.x
com.atlassian.bitbucket.ServiceException
The monolithic com.atlassian.stash.exception
package has been removed. The exceptions it previously contained have been moved into the module they belong to. For example, NoSuchRepositoryException
is now in the com.atlassian.bitbucket.repository
package.
Java User model
Stash 3.x
com.atlassian.stash.user.StashUser
Bitbucket 4.x
com.atlassian.bitbucket.user.ApplicationUser
Java Authentication Context
Stash 3.x
com.atlassian.stash.user.StashAuthenticationContext
Bitbucket 4.x
com.atlassian.bitbucket.auth.AuthenticationContext
Java Event model
Stash 3.x
com.atlassian.stash.event.StashEvent
Bitbucket 4.x
com.atlassian.bitbucket.event.ApplicationEvent
The monolithic com.atlassian.stash.event
package has been broken down and the events it formerly contained have been moved into subpackages. For example, RepositoryCreatedEvent
is now in com.atlassian.bitbucket.event.repository
Java model
Stash 3.x
Changeset,
DetailedChangeset
Bitbucket 4.x
Commit, Changeset
We've standardized our naming:
- A "commit" is an event where the contents of a repository are changed
- A "changeset" is the set of changes that exist between two commits
- The codebase no longer uses the words "changeset" and "commit" interchangeably; each word refers to a specific concept
All classes and interfaces with Changeset
in the name have replaced with an equivalent class or interface with Commit
in the name instead.
What was formerly a DetailedChangeset
, because the object that should have been called a Commit
had already stolen the Changeset
name, is now called a Changeset
Java Pull Request Participant model
Stash 3.x
PullRequestParticipantSearchRequest
PullRequestParticipantSearchCriteria
Bitbucket 4.x
PullRequestParticipantRequest
PullRequestParticipantCriteria
Soy templates
Stash 3.x
changeset
Bitbucket 4.x
commit
Application constants
Stash 3.x
com.atlassian.stash.Product
#NAME="Stash"
#DATA_CENTER_NAME="Stash Data Center"
#FULL_NAME="Atlassian Stash"
Bitbucket 4.x
com.atlassian.bitbucket.Product
#NAME="Bitbucket"
#DATA_CENTER_NAME="Bitbucket Data Center"
#FULL_NAME="Atlassian Bitbucket"
License changes
Stash 3.x
com.atlassian.extras.api.stash.StashLicense
Bitbucket 4.x
com.atlassian.extras.api.bitbucket.BitbucketServerLicense
Add this dependency to your POM:
<dependency>
<groupId>com.atlassian.extras</groupId>
<artifactId>atlassian-extras-api</artifactId>
<scope>provided</scope>
</dependency>
Javascript API modules
Stash 3.x
stash/api/*
(eg.stash/api/util/server
)
Bitbucket 4.x
bitbucket/*
(eg.bitbucket/util/server
)
Soy API namespaces
Stash 3.x
stash.template.branchSelector
Bitbucket 4.x
bitbucket.component.branchSelector
Web API plugin module
Stash 3.x
com.atlassian.stash.stash-web-api
Bitbucket 4.x
com.atlassian.bitbucket.server.bitbucket-web-api
Note there have been a number of new API resources added, which allow you to better express your web resources dependencies. Please see the updated Web UI API documentationfor more detail about these resources.
Core web plugin module
Stash 3.x
com.atlassian.stash.stash-web-plugin
Bitbucket 4.x
This core plugin contains internal modules only and should not be referenced by other plugins.
Web Panel & Section Locations
Stash 3.x
stash.*
e.g. stash.branch.list.actions.dropdown
Bitbucket 4.x
bitbucket.*
e.g. bitbucket.branch.list.actions.dropdown
Web Resource Contexts
Stash 3.x
stash.*
e.g. stash.layout.pullRequest
Bitbucket 4.x
bitbucket.*
bitbucket.layout.pullRequest
Plugin decorators
Stash 3.x
stash.*
e.g. stash.repository.settings
Bitbucket 4.x
bitbucket.*
bitbucket.repository.settings
See plugin decorators documentation
Web Resource Modules
Stash 3.x
<stash-resource/>
Bitbucket 4.x
<client-resource/>
Note that client-resource
will expand <directory/>
elements in-place, where stash-resource
expanded them at the end.
Web Item icons (in atlassian-plugin.xml)
Stash 3.x
<param name="stashIconClass">...</param>
Bitbucket 4.x
<param name="iconClass">...</param>
Web I18n
Stash 3.x
stash_i18n
Bitbucket 4.x
getText
、getTextAsHtml
stash_i18n
should not be used; getText
is a cross-product replacement that doesn't accept a default translation parameter. See Writing Soy Templates for usage details. Note that these templates for Confluence work for Bitbucket too.
Form Fragments
Stash 3.x
stash.*
Bitbucket 4.x
bitbucket.*
Javascript Events
Stash 3.x
stash.*
Bitbucket 4.x
bitbucket.internal.*
See below for additional information about JavaScript events.
I18n keys
Stash 3.x
stash.*
Bitbucket 4.x
bitbucket.*
Java API - Guava
Stash 3.x
com.google.common.base.Function/Predicate
Guava 11 was available to plugins
Bitbucket 4.x
Java 8 Lambdas
Guava types like Function or Predicate are no longer used in API type signatures, use the corresponding types from java.util.function instead
Guava 18 is available to plugins
Servlet Dependency
Stash 3.x
<groupId>javax.servlet</groupId>
<artifactId>servlet-api</artifactId>
<scope>provided</scope>
</dependency>
Bitbucket 4.x
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<scope>provided</scope>
</dependency>
The artifactId has changed to javax.servlet-api from servlet-api.
ブランチの権限
Stash 3.x
canDelete, canWrite
検索
Bitbucket 4.x
hasPermission
Checking for access to a Ref
is now done by calling the RefRestrictionService's
method.hasPermission
The search
method for AccessGrants
has been removed. AccessGrants
can now be accessed by calling getAccessGrants
on a RefRestriction
.
Exported 3rd party libraries
Stash 3.x
Apache HTTP Client 3.x is no longer exported by the host app.
Bitbucket 4.x
Use HTTP Client 4.x instead.
<dependency>
<groupId>org.apache.httpcomponents</groupId>
<artifactId>httpclient</artifactId>
<scope>provided</scope>
</dependency>
SAL Scheduler deprecated
Stash 3.x
SAL 2.0
com.atlassian.sal.api.scheduling.PluginScheduler
(Since Bitbucket 4.0.0 will throw an IllegalArgumentException if any job data passed to
scheduleJob does not implement java.io.Serializable)
Bitbucket 4.x
SAL 3.0
(see SAL 3.0 upgrade guide for further details)
Use com.atlassian.scheduler.SchedulerService
provided by:
<groupId>com.atlassian.scheduler</groupId>
<artifactId>atlassian-scheduler</artifactId>
instead.
Outline of changes made to the REST API
The payloads for some of the REST resources have changed. All URLs are the same except that the default context path is now /bitbucket
instead of /stash
.
Self Links
Some REST model classes, like RestStashUser
, had their "self" links defined two ways:
"link": {
"url": "/users/admin",
"rel": "self"
},
"links": {
"self": [
{
"href": "http://localhost:7990/stash/users/admin"
}
]
}
The "link"
attribute is from 1.0 and was deprecated in 2.11. From 4.0, the "link"
attribute has been removed. The "self"
entry in the "links"
map remains.
Changeset
to Commit
Ref output, such as branches and tags, had a "latestChangeset"
attribute. The following output is from the /projects/KEY/repos/slug/branches
resource:
{
"size": 1,
"limit": 1,
"isLastPage": false,
"values": [
{
"id": "refs/heads/search/STASHDEV-8813-search",
"displayId": "search/STASHDEV-8813-search",
"latestChangeset": "de307ea7b6abfa1aad8de6771d79da0a9a7fd3cb",
"latestCommit": "de307ea7b6abfa1aad8de6771d79da0a9a7fd3cb",
"isDefault": false
}
],
"start": 0,
"nextPageStart": 1
}
A "latestCommit"
attribute was added in 3.7 and "latestChangeset"
was deprecated. It has been removed in 4.0. This also applies to pull request refs.
AttributeMap
to PropertyMap
Some REST objects, most notably RestPullRequest
, had an "attributes"
attribute which allowed plugin developers to attach arbitrary data. However, the model for this was very restrictive, being defined in AttributeMap
as Map<String, Set<String>>
. In 3.2, PropertyMap
, defined as Map<String, Object>
, was added to replace the attribute support. However, for performance and API consistency reasons, most existing attributes were not converted over. In 4.0, the changeover is now complete.
The following JSON snippets show the old and new layouts for pull request properties.
As you can see, the new "properties"
map allows its numeric entries to be numeric, resulting in much more readable, useful output.
PullRequestOrder
default order
The getDefaultOrderForState(PullRequestState state)
method in PullRequestOrder
has been replaced withgetDefaultOrder()
, which always returns PullRequestOrder.NEWEST
.
XSRF Protection enabled by default
To prevent a malicious hacker submitting a form from a foreign site to a stash instance, XSRF protection has now been enabled by default on all REST resources which do not accept the "application/json" Content-Type.
Any client POSTing to these resources will need to add a special header to disable this check.
Header name: X-Atlassian-Token
Header value: no-check
For example, to set a Project Avatar via curl, the following command can be used:
$ curl -X POST -u username:password -H "X-Atlassian-Token: no-check" http://localhost:8080/rest/api/1.0/projects/TEST/avatar.png -F avatar=@avatar.png
The -H "X-Atlassian-Token: no-check"parameter was not needed in 3.x, however is now needed since 4.0
For your own REST resources which do not accept "application/json" (e.g. multipart/form-data, plain/text etc), you can opt-out of XSRF protection by using the @XsrfProtectionExcluded annotation.
If you use the excluded annotation, it should be because your endpoint has some other type of protection against XSRF/CSRF attacks.
Javascript Events
Since Stash 3.0 we have provided a Javascript API module for creating and consuming events (stash/api/util/events
, now bitbucket/util/events
), however we haven't documented what events Bitbucket (Stash) emits as part of our Developer Docs. Which events should be used and which should be considered internal implementation details were subject to change.
We are actively looking at which events we should consider part of the API. We will document usage and guarantee the stability for events that are part of the API for a major version. We would like to hear any feedback on which events you make use of in your apps, and why, to aid in our consideration of what to consider for the JS Events API.
App update strategies
There are two primary strategies we are suggesting to update your app, and here we explain how to implement each and how to provide support for your app going forward.
Hard break
The simplest way forward is to branch your app and only release Bitbucket Server 4.0 compatible versions in the future. Replace the old com.atlassian.stash dependency
with the new com.atlassian.bitbucket
one, fix the resulting compilation errors, and create a new listing on Marketplace.
Backwards/forwards compatibility
The best way to achieve this is to maintain a branch of the "Stash" version of your plugin, and merge changes onto a master branch which contains the "Bitbucket server" version.
Unfortunately, unless you have written a pure cross-product app, building two versions from the same branch of code is in general not worth the overhead.
Rename checklist
- Beware of changing any Strings which are used as keys for accessing data your app may store. e.g. namespaces used with
PluginSettingsFactory.createSettingsForKey
or prefixes used withApplicationPropertyService.getPluginProperty
- We strongly recommend that you do not change your app key; if you do, customers won't be able to see the updated version of your app in their Universal Plugin Manager. The default
atlassian-plugin.xml
generated by AMPS useskey="${project.groupId}.${project.artifactId}"
. Changing your MavengroupId
orartifactId
this will change your app key. If you are using ActiveObjects, you are strongly encouraged to set the
namespace
attribute to ensure the unique hash in your table names does not change. Otherwise anyone who has installed your plugin will "lose" all of their data when your plugin starts using new tables!
For example, here's how we defined the<ao/>
module in our ref sync plugin:<ao key="ao" namespace="com.atlassian.stash.stash-repository-ref-sync">