アドオンの更新方法
バックエンドの変更
One of the exciting changes with this release is the new JDK minimum requirement of 1.8, that allows you to use a wide new array of language features in your app code. While Stash 3.x supports running on Java 8; Bitbucket Server supports compiling to Java 8.
The largest change was we renamed our package namespace from com.atlassian.stash
to com.atlassian.bitbucket
, but this should also be a simple change when you update your plugins. The Bitbucket Server team updated over 100 apps internally and the process was quite straightforward using refactoring support in modern IDEs.
再パッケージに加え、コードベースからすべての @deprecated API を削除しました。これらのほとんどには既存の置き換えメソッドが設定されていましたが、一部は置き換えられることなく削除されました。新しいメソッドが明確でない場合は最新の Stash 3.x ドキュメントで、使用すべき置き換えメソッドの詳細をご覧いただけます。
Finally, several of our bundled plugins were exporting API (our com.atlassian.stash:stash-build-integration
plugin, for example), which meant plugin developers added dependencies on that jar. However, only a small portion of the code in that jar was exported. This was a frequent source of plugin issues because plugin developers attempted to use our internal classes. In 4.0, the exported APIs from all of our plugins have been extracted into separate modules (like with the stash-build-integration
example, the build API is now in com.atlassian.bitbucket.server:bitbucket-build-api
). These new API modules contain all of the code that is published for plugin developers to use.
フロントエンドの変更
Our Javascript and Soy API modules have moved to the Bitbucket namespace. AMD Modules, previously found under stash/api/*
, are now bitbucket/*
. Non-API modules will be under bitbucket/internal
. For example, stash/api/util/navbuilder
is now bitbucket/util/navbuilder
. For API Soy templates, these are now also under the bitbucket
namespace - Stash.template.branchSelector
is now bitbucket.component.branchSelector
.
Another front-end change is that most keys – including Form Fragments, Web Panel & Section locations, and Web Resource apps – have been moved to Bitbucket namespaces. There is more detail on these changes below.
4.0 での削除を前提に非推奨となっていたメソッドやモジュールは削除されました。
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 Server 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.
たとえば、pom.xml で、以下の変数の値を、groupId と artifactId の値に置き換えます。
<atlassian-plugin key="${project.groupId}.${project.artifactId}" ...
Bitbucket Server 4.0 の最新バージョンを参照するように pom.xml を更新します。Bitbucket Server と AMPS の両方のバージョン プロパティを更新する必要があります。これには現在、Bitbucket Server プラグインをビルドするためのプレリリース バージョンと、任意の API アーティファクトへの依存関係が必要となります。
<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>
オプション: プラグインが Bitbucket Server のみをサポートする場合は、Stash の依存関係を削除します。
<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. - IDE が提供するインポート候補を使用し、API の変更履歴と以下の表を確認します。
- 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
- フロントエンド 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
その他の便利なリソース
- Bitbucket Server の開発者向けドキュメント。
- "bitbucket-server" トピックで Atlassian Answers に質問を投稿できます。
- 「サポート終了のお知らせ」を参照し、このポリシーの最新情報をご確認ください。
API の変更の概要
Java パッケージ
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" ...>
(いずれの場合も変更しないでください)
<atlassian-plugin key="com.myorg.stash.awesome-plugin" ...>
Maven プラグイン
Stash 3.x
<artifactId>maven-stash-plugin</artifactId>
例:
<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>
例:
<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>
例外
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 モデル
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 モデル
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 モデル
Stash 3.x
Changeset,
DetailedChangeset
Bitbucket 4.x
Commit, Changeset
命名規則を標準化しました。
- "commit" は、リポジトリのコンテンツが変更されたイベントです
- "changeset" は、2 つのコミット間に存在する変更のセットです
- コードベースは "changeset" と "commit" という単語を互換的に使用しなくなりました。それぞれの単語は固有の概念を表します。
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 モデル
Stash 3.x
PullRequestParticipantSearchRequest
PullRequestParticipantSearchCriteria
Bitbucket 4.x
PullRequestParticipantRequest
PullRequestParticipantCriteria
Soy テンプレート
Stash 3.x
チェンジセット
Bitbucket 4.x
commit
アプリケーションの定数
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"
ライセンスの変更
Stash 3.x
com.atlassian.extras.api.stash.StashLicense
Bitbucket 4.x
com.atlassian.extras.api.bitbucket.BitbucketServerLicense
POM に次の依存関係を追加します。
<dependency>
<groupId>com.atlassian.extras</groupId>
<artifactId>atlassian-extras-api</artifactId>
<scope>provided</scope>
</dependency>
Javascript API モジュール
Stash 3.x
stash/api/*
(eg.stash/api/util/server
)
Bitbucket 4.x
bitbucket/*
(eg.bitbucket/util/server
)
Soy API の名前空間
Stash 3.x
stash.template.branchSelector
Bitbucket 4.x
bitbucket.component.branchSelector
Web API プラグイン モジュール
Stash 3.x
com.atlassian.stash.stash-web-api
Bitbucket 4.x
com.atlassian.bitbucket.server.bitbucket-web-api
ここまでで多数の API リソースを追加済みのため、web リソースの依存関係をより表現することができます。これらのリソースの詳細については、Web UI API の更新済みのドキュメントをご確認ください。
Core web プラグイン モジュール
Stash 3.x
com.atlassian.stash.stash-web-plugin
Bitbucket 4.x
core プラグインには内部モジュールのみが含まれます。このプラグインをほかのプラグインで参照することはできません。
Web パネルとセクションの場所
Stash 3.x
stash.*
e.g. stash.branch.list.actions.dropdown
Bitbucket 4.x
bitbucket.*
e.g. bitbucket.branch.list.actions.dropdown
Web リソースのコンテキスト
Stash 3.x
stash.*
e.g. stash.layout.pullRequest
Bitbucket 4.x
bitbucket.*
bitbucket.layout.pullRequest
プラグインのデコレーター
Stash 3.x
stash.*
e.g. stash.repository.settings
Bitbucket 4.x
bitbucket.*
bitbucket.repository.settings
Web リソースのモジュール
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 アイテムのアイコン (atlassian-plugin.xml 内)
Stash 3.x
<param name="stashIconClass">...</param>
Bitbucket 4.x
<param name="iconClass">...</param>
Web の国際化
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.
フォームのフラグメント
Stash 3.x
stash.*
Bitbucket 4.x
bitbucket.*
JavaScript イベント
Stash 3.x
stash.*
Bitbucket 4.x
bitbucket.internal.*
JavaScript イベントの追加情報については以降をご確認ください。
国際化のキー
Stash 3.x
stash.*
Bitbucket 4.x
bitbucket.*
Java API - Guava
Stash 3.x
com.google.common.base.Function/Predicate
プラグインで Guava 11 を利用できました。
Bitbucket 4.x
Java 8 Lambdas
Function や Predicate などの Guava タイプは API タイプ署名では使用されなくなりました。java.util.function の対応するタイプを使用してください。
プラグインで Guava 18 を利用できます
サーブレットの依存関係
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>
artifactId は servlet-api から javax.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
.
エクスポートされたサードパーティ ライブラリ
Stash 3.x
Apache HTTP Client 3.x はホスト アプリによってエクスポートされなくなりました。
Bitbucket 4.x
代わりに HTTP Client 4.x を使用します。
<dependency>
<groupId>org.apache.httpcomponents</groupId>
<artifactId>httpclient</artifactId>
<scope>provided</scope>
</dependency>
SAL Scheduler の非推奨
Stash 3.x
SAL 2.0
com.atlassian.sal.api.scheduling.PluginScheduler
(Bitbucket 4.0.0 は scheduleJob に渡されたジョブが
java.io.Serializable を実装しない場合、IllegalArgumentException を返すため)
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>
を使用します。
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 リンク
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.
次の JSON スニペットは、プル リクエストのプロパティの古いレイアウトと新しいレイアウトを表示します。
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 保護を既定で有効化
悪意のあるユーザーが外部のサイトから Stash インスタンスにフォームを送信することを防ぐため、すべての REST リソースで XSRF 保護が既定で有効化されるようになりました。これは "application/json" Content-Type を許可しません。
これらのリソースに POST するすべてのクライアントは、この確認を無効化するために特別なヘッダーを追加する必要があります。
ヘッダー名: X-Atlassian-Token
ヘッダー値: no-check
たとえば、curl 経由でプロジェクトのアバターを設定したい場合、次のコマンドを使用できます。
$ 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
-H "X-Atlassian-Token: no-check" パラメーターは 3.x では不要でしたが、4.0 以降では必要になりました。
"application/json" を許可しない (例: multipart/form-data、plain/text) 自身の REST リソースでは、@XsrfProtectionExcluded アノテーションを使用して XSRF 保護からオプトアウトできます。
除外されたアノテーションを使用している場合、XSRF/CSRF 攻撃への他のタイプの保護がエンドポイントで行われている可能性が考えられます。
JavaScript イベント
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.
互換性なし
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.
前方/後方互換性
これを実現する最適な方法は、プラグインの "Stash" バージョンのブランチを保持し、"Bitbucket Server" バージョンを含む master ブランチに変更をマージすることです。
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.
チェックリストの名前変更
- 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">