Skip to content

Commit 73fb6d2

Browse files
author
Dmitri Zimine
committed
Upgrade notes and transition
1 parent 201fd97 commit 73fb6d2

5 files changed

Lines changed: 99 additions & 79 deletions

File tree

‎docs/source/packs.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Managing Packs
2626
Everything about packs got better and easier in |st2| 2.1! There are new API endpoints, CLI
2727
commands, repository structure for hosting packs, and an awesome pack collection on `StackStorm
2828
Exchange <https://exchange.stackstorm.org>`_. To make it happen, we deprecated few old things.
29-
Check the :doc:`upgrade notes </upgrade_notes>` and :doc:`/reference/packmgmt`.
29+
Check the :doc:`upgrade notes </upgrade_notes>` and :doc:`/reference/pack_management_transition`.
3030

3131
|st2| packs are managed through ``st2 pack ...`` commands: ``st2 pack -h`` will give you a useful overview if you just need a quick start.
3232

‎docs/source/reference/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,9 @@ References and Guides
55
:maxdepth: 2
66

77
cli
8-
packmgmt
98
pack_configs
109
packs
10+
pack_management_transition
1111
jinja
1212
policies
1313
runners

‎docs/source/reference/pack_management_transition.rst‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
Pack Management Transition
2+
==========================
3+
4+
.. warning:: The introduction of new pack management and
5+
`StackStorm Exchange <https://exchange.stackstorm.org/>`__ lead to the changes that may require users
6+
to update their custom :doc:`/packs`. All community packs are updated to work with |st2| 2.1
7+
(and will still work with older versions of |st2|). Read on for details.
8+
9+
10+
In |st2| 2.1, pack management have received significant overhaul. With new dedicated tools, working with packs becomes very close to the "usual" package management you know from working with
11+
development platforms and Linux flavours. Installing, updating, and managing StackStorm packs has become a smoother, more streamlined experience.
12+
13+
It's a big change, and you will surely enjoy the streamlined workflow for content management. By
14+
assuming `git`, making ``one pack - one git repo`` convention, and building tooling around it, we
15+
now streamlined pack development and lifecycle. Developing a pack, contributing a fix to Community,
16+
checking deviation between production and upstream origins, handling versions, sharing and
17+
discovering your automations and integrations - all of it is becoming a breeze.
18+
19+
However we had to make some changes that will require you to
20+
update your private packs, or to make or adjusting automation tools might use to
21+
deploy and configure your packs on |st2|.
22+
23+
24+
Good bye st2contrib, long live StackStorm Exchange
25+
--------------------------------------------------
26+
27+
`StackStorm Exchange <https://exchange.stackstorm.org/>`__ is the new pack index maintained by the StackStorm team. Any pack from StackStorm Exchange can be installed with ``st2 pack install <pack>``
28+
in the CLI. No WebUI support yet.
29+
30+
Exchange packs are hosted in the `StackStorm-Exchange organization
31+
<https://github.com/stackstorm-exchange>`__ on GitHub. To submit **a new pack** to the StackStorm Exchange, follow the instructions in
32+
`exchange-incubator <https://github.com/stackstorm-exchange/exchange-incubator>`__.
33+
34+
All the packs from `st2contrib <https://github.com/stackstorm/st2contrib>`__ have been migrated to
35+
individual repositiroes at `StackStorm-Exchange organization <https://github.com/stackstorm-exchange>`.
36+
The `st2contrib <https://github.com/stackstorm/st2contrib>`__ repository is frozen. It is still
37+
functional, but it will not receive updates anymore, and new submissions are not accepted.
38+
39+
40+
Warnings - check your packs
41+
---------------------------
42+
43+
Please validate your custom packs against these two changes:
44+
45+
* The version field must conform to semver (semantic versioning): ``0.2.5``, not ``0.2``. If it does not, the pack registration will throw an error. Please check and update.
46+
* The name field in pack.yaml should now only contain contain letters, digits, and underscores. No dashes! ``hpe-icsp`` is no good, ``hpe_icsp`` is fine.
47+
* The email attribute, if present in pack.yaml, must contain a properly formatted email address.
48+
49+
Fix your packs to conform to these rules; follow the steps in :doc:`/upgrade_notes` to upgrade.
50+
51+
Subtree repositories (repositories containing multiple packs inside the packs/ subdir) are no longer
52+
supported. The ``subtree`` parameter in packs.install is removed. If you happen to use subtrees with
53+
your private packs on git/GitHub, they will have to be split into multiple single-pack repositories in order for ``st2 pack install`` to be able to install the packs.
54+
55+
Changes to take advantage
56+
-------------------------
57+
58+
.. TODO:: DZ: finish this up...
59+
60+
-------------
61+
62+
.. include:: ../__engage_community.rst

‎docs/source/reference/packmgmt.rst‎

Lines changed: 0 additions & 42 deletions
This file was deleted.

‎docs/source/upgrade_notes.rst‎

Lines changed: 35 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -6,25 +6,45 @@ Upgrade Notes
66
|st2| in development
77
--------------------
88

9-
* StackStorm Exchange is introduced, and st2contrib is now deprecated. For more information see
10-
:doc:`/reference/packmgmt`.
9+
* **WARNING:** The following changes may require you to update your packs during the upgrade.
1110

12-
* Pack names and action parameter names can now only contain valid word characters (``a-z``,
13-
``0-9`` and ``_``).
11+
* The ``version`` attribute in ``pack.yaml`` metadata must now contain
12+
to contain a valid ``semver`` version string (<major>.<minor>.<patch>, e.g. ``1.0.1``). In
13+
addition to that, ``email`` attribute must be a valid email address.
1414

15-
If you have an existing pack or action which uses parameter name which doesn't fall into this
16-
criteria it needs to be updated otherwise pack / action registration will fail with an error.
15+
* Pack ``ref`` and action parameter names can now only contain valid word characters (``a-z``,
16+
``0-9`` and ``_``). No dashes! ``hpe_icsp`` is ok, but ``hpe-icsp`` is not.
1717

18-
* The ``packs`` pack is deprecated starting from 2.1, in future versions it will be completely
19-
replaced with the ``st2 pack <...>`` commands and API endpoints. See :doc:`/reference/packmgmt`
20-
for the transition reference.
18+
The ``st2ctl`` and ``st2-register-content`` scripts are now doing additional validation. If you
19+
happen to have a pack which doesn't satisfy these new validation criteria, it will fail to load.
20+
Therefore, to upgrade from `2.0.*` StackStorm instance to `2.1.*`, follow this:
2121

22-
* The ``packs.install`` action has been reworked, and subtree (multi-pack) repositories are no
23-
longer supported due to the StackStorm Exchange transfer.
22+
1. Use `yam` or `apt-get` to upgrade to the newest version.
23+
2. Run `st2ctl reload`.
24+
3. If you have packs that don't satisfy the rules above, the validation fails
25+
and the pack load will throw errors. Fix the packs to conform the rules above,
26+
and run `st2ctl reload` again.
27+
4. TODO: we will provide a script to auto-adjust all the packs.
28+
29+
* `st2contrib <https://github.com/stackstorm/st2contrib>`__ is now deprecated, and replaced by
30+
`StackStorm Exchange <https://exchange.stackstorm.org/>`__ . All the packs from
31+
`st2contrib <https://github.com/stackstorm/st2contrib>`__ are migrated to StackStorm Exchange.
32+
For more information see :doc:`/reference/pack_management_transition`.
33+
34+
* Pack "subtree" repositories (repositories containing multiple packs inside the ``packs/`` subdir)
35+
are no longer supported. The subtree parameter in packs.install is removed. The new convention is
36+
one pack per git/GitHub repo. If you happen to use subtrees with your private packs, they will
37+
have to be split into multiple single-pack repositories in order for st2 pack install to be able
38+
to install the packs.
39+
40+
* The ``packs`` pack is deprecated starting from 2.1; in future versions it will be completely
41+
replaced with the ``st2 pack <...>`` commands and API endpoints.
42+
43+
* Pack metadata file (``pack.yaml``) can now contain a new ``ref`` attribute, in addition to `name`.
44+
`ref` acts as a unique identifier; it offers for a more readable ``name``. For example, if a pack name is ``Travis CI``, a repo containing it is stackstorm-travis_ci, and ``ref`` is ``travis_ci``. Previously the pack files would live in ``travis_ci/`` directory and pack directory name served as a unique identifier for a pack.
2445

2546
* Support for ``.gitinfo`` file has been removed and as such ``packs.info`` action has also been
26-
removed. All the local pack directories are now direct git checkouts of the corresponding pack
27-
repositories so this file is not needed anymore.
47+
removed. All the pack directories at ``/opt/stackstorm/packs`` are now direct git checkouts of the corresponding pack repositories from exchange or your own origin, so this file is not needed anymore.
2848

2949
* Datastore scopes are now ``st2kv.system`` and ``st2kv.user`` as opposed to ``system`` and ``user``.
3050
So if you are accessing datastore items in your content, you should now use jinja expressions
@@ -38,22 +58,6 @@ Upgrade Notes
3858
No backward compatibility is guaranteed. Please wait for a release note indicating general
3959
availability of this feature.
4060

41-
* When registering packs using ``st2ctl`` / ``st2-register-content`` script additional validation
42-
is now performed on the pack metadata (``pack.yaml`` file). The ``version`` attribute now needs
43-
to contain a valid ``semver`` version string (<major>.<minor>.<patch>, e.g. ``1.0.1``). In
44-
addition to that, ``email`` address attribute now also needs to contain a valid email address.
45-
46-
If you have an existing pack which doesn't satisfy this new validation criteria it needs to be
47-
updated otherwise pack registration will fail.
48-
49-
* Pack metadata file (``pack.yaml``) can now contain a new ``ref`` attribute. This attribute acts as
50-
a unique identifier for a pack and should be specified when a pack files don't live in a
51-
sub-directory (e.g. such as with the new single pack per git repository model). Previously, pack
52-
directory served as a unique identifier for a pack.
53-
54-
For example, if a pack name is ``Travis CI``, a valid and good value for ``ref`` attribute would
55-
be ``travis_ci`` (previously the pack files would live in ``travis_ci/`` directory).
56-
5761
* Config schemas now also support nested objects. Previously config schema and configuration file
5862
needed to be fully flat to be able to utilize default values from the config schemas and dynamic
5963
configuration values inside the config file.
@@ -131,12 +135,8 @@ Upgrade Notes
131135
type: "integer"
132136
required: true
133137
134-
* ``version`` field in the pack metadata file must now contain a version string which is a
135-
valid semver identifier - ``<major>.<minor>.<patch>``. For example ``0.1.0``, ``1.0.0,``2.0.1``,
136-
etc.
137-
138-
|st2| v2.0.0
139-
------------
138+
|st2| v2.0
139+
----------
140140

141141
* `st2ctl reload` now also registers rules by default. Prior to this release we used to register
142142
actions, aliases, sensors, triggers and configs. Now rules are also registered by default.

0 commit comments

Comments
 (0)