You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@brooklyn.apache.org by Aled Sage <al...@gmail.com> on 2017/10/26 11:06:38 UTC
[PROPOSAL] catalog bundle id:version mandatory in v1.0.0
Hi all,
I propose we make it mandatory to specify the bundle id and version
(currently it is optional).
I think we should do this asap, before 1.0.0 is released.
This is a breaking change - it will require users to add a `bundle: ...`
line to their .bom files (if they are not supplying the metadata another
way, such as building their project as an OSGi bundle).
TL;DR: for backwards compatibility, we let users have a different mental
model from what Brooklyn now actually does, which can lead to confusing
behaviour when upgrading or working with snapshots.
*## Current Behaviour*
Currently, we'll auto-wrap things as a bundle, generating a unique
anonymous bundle name:version if one is not supplied.
This is important for users doing `br catalog add myfile.bom` or `br
catalog add mydir/`. In both cases we automatically create an OSGi
bundle with those contents. For that bundle's name:version, one can
explicitly supply it (e.g. via `bundle: ...` in the .bom file). But, for
backwards compatibility, we support .bom files that have no such metadata.
*## Old Behaviour (0.11.0 and Earlier)*
Before we added full support and use of bundles in the catalog, the
user's .bom file was parsed and its items added to the catalog. The raw
.bom file was discarded.
For upgrade/dependencies/versioning/usability reasons described in
[1,2,3], this was a bad idea.
*## Reason the Current Behaviour is Bad!*
By auto-generating bundle names, we allow users to have a completely
different mental model from what is actually happening in Brooklyn.
For simple cases (e.g. their .bom file only ever contains one item),
that's fine.
However, it leads to surprising behaviour (and more complicated Brooklyn
code), particularly when using snapshots or forced upgrade.
Consider a (developer) user writing a .bom file, with version
1.0.0-SNAPSHOT containing entities A and B. If the user modifies it and
runs `br catalog add myfile.bom` then we successfully replace the old
auto-generated bundle with this new one. However, if the user then
deletes B (so the .bom contains only A) and does `catalog add` again,
it's unclear to Brooklyn whether this is meant to be the same .bom file.
You could argue that it should be forbidden (because if we kept the old
.bom we'd end up with two different versions of A, and deleting B would
be wrong if it was a different .bom).
The right thing in my opinion is to force the user to have the same
mental model as Brooklyn does: they need to include a `bundle: ` line in
their .bom file so they are explicit about what they are doing.
Note this does not force the user to understand OSGi/java; it just
requires them to think in terms of a "versioned bundle" of catalog items.
Aled
[1] "Uploading ZIPs for a better dev workflow" dev@brooklyn email thread
[2] "Bundles in Brooklyn" dev@brooklyn email thread
[3] "Bundles of fun" dev@brooklyn email thread
Re: [PROPOSAL] catalog bundle id:version mandatory in v1.0.0
Posted by Alex Heneveld <al...@cloudsoftcorp.com>.
We jump through quite a few hoops to ensure rebind works, including
current PR [1]. (I might feel differently if I haven't just spent too
long making those hoops.)
Code will be able to be simplified quite a bit in this area if we
disallow the so-called "anonymous bundles" - but feels premature to go
that far.
--A
[1] https://github.com/apache/brooklyn-server/pull/866
On 27/10/2017 09:21, Thomas Bouron wrote:
> Fair points Alex, you are absolutely right.
>
> Although, I still think that forcing to have `bundle:` now in a bom is
> a better way: It will be annoying for users but easy to fix, whereas
> the alternative means that it Brooklyn **will be broken on
> restart/rebind** which is a clear no-go from my point of view.
>
> Best
>
> On Fri, 27 Oct 2017 at 09:12 Alex Heneveld
> <alex.heneveld@cloudsoftcorp.com
> <ma...@cloudsoftcorp.com>> wrote:
>
>
> Thinking about it I'm not convinced that breaking users blueprints
> is the best way to update their mental model. With a shift to use
> the CLI with catalog.bom in root and updating exemplar projects,
> and updating UI to reflect bundles, I expect we'll achieve this in
> a less disruptive way.
>
> At minimum I don't think we should make it a breaking change to
> try to force a mental model switch until _we_ have:
>
> * made catalog UI be bundle-centric (currently bundle name is
> shown but you can't navigate by bundles)
> * made composer be bundle-centric - at minimum including a bundle
> name in the template Brooklyn shows, but ideally more, allowing
> people to edit multiple resources in a bundle via the UI (else we
> aren't really operating on the new mental model)
>
> We will also need a non-trivial amount of work to update tests
> probably the majority of which use anonymous bundles and many of
> which test aspects of anonymous bundles (and we'd have to be
> careful in updating/fixing tests to identify the latter ones).
>
>
> Some halfway house measures would be to provide more obvious
> feedback to users when they install or use anonymous bundles:
>
> * CLI and UI show the name of the bundle added, with a warning if
> it's an anonymous one (user can then easily delete and release
> with better name)
> * UI show warnings on items from anonymous bundles
>
>
> Also maybe it's worth adding a "strict" mode to Brooklyn, where in
> strict mode this is disabled (and other things, like
> persisting/rebinding anonymous types or other deprecated
> features). We could even persist this setting so new users work
> in strict mode but if you're rebinding you get non-strict mode.
>
> Best
>
> Alex
>
>
>
> On 27/10/2017 08:16, Thomas Bouron wrote:
>> +1, this sounds sensible to me too.
>> I also vote in favor of making this a breaking change. With 1.0.0
>> coming, this is the perfect time to do it.
>>
>> Best.
>>
>> On Fri, 27 Oct 2017 at 08:06 Geoff Macartney
>> <geoff.macartney@cloudsoft.io
>> <ma...@cloudsoft.io>> wrote:
>>
>> +1 to your suggestion Aled. Also I'd side with making it a
>> breaking
>> change, I prefer forcing that mental model.
>>
>> On Thu, 26 Oct 2017 at 13:12 Aled Sage <aled.sage@gmail.com
>> <ma...@gmail.com>> wrote:
>>
>> > Alex,
>> >
>> > I say we break it - force the user to have the correct
>> mental model for
>> > 1.0.0!
>> >
>> > It's a simple one-line addition to fix a given .bom file.
>> We should
>> > obviously ensure that historic persisted state continues to
>> work.
>> >
>> > ---
>> >
>> > Also note that our deprecation warnings are too hidden. For
>> example, if
>> > you do `br catalog add ...` then deprecation warnings will
>> only be
>> > visible via the Brooklyn log (rather than being returned to
>> the user of
>> > `br` or via the REST api).
>> >
>> > But that's a separate topic!
>> >
>> > Aled
>> >
>> >
>> > On 26/10/2017 12:58, Alex Heneveld wrote:
>> > >
>> > > Absolutely.
>> > >
>> > > Question is whether we should deprecate or make it a
>> breaking change.
>> > >
>> > > Deprecating feels right, though I think it would mean we
>> can't
>> > > actually remove until 2.0 ?
>> > >
>> > > Best
>> > > Alex
>> > >
>> > >
>> > > On 26/10/2017 12:06, Aled Sage wrote:
>> > >> Hi all,
>> > >>
>> > >> I propose we make it mandatory to specify the bundle id
>> and version
>> > >> (currently it is optional).
>> > >>
>> > >> I think we should do this asap, before 1.0.0 is released.
>> > >>
>> > >> This is a breaking change - it will require users to add
>> a `bundle:
>> > >> ...` line to their .bom files (if they are not supplying
>> the metadata
>> > >> another way, such as building their project as an OSGi
>> bundle).
>> > >>
>> > >> TL;DR: for backwards compatibility, we let users have a
>> different
>> > >> mental model from what Brooklyn now actually does, which
>> can lead to
>> > >> confusing behaviour when upgrading or working with
>> snapshots.
>> > >>
>> > >> *## Current Behaviour*
>> > >>
>> > >> Currently, we'll auto-wrap things as a bundle,
>> generating a unique
>> > >> anonymous bundle name:version if one is not supplied.
>> > >>
>> > >> This is important for users doing `br catalog add
>> myfile.bom` or `br
>> > >> catalog add mydir/`. In both cases we automatically
>> create an OSGi
>> > >> bundle with those contents. For that bundle's
>> name:version, one can
>> > >> explicitly supply it (e.g. via `bundle: ...` in the .bom
>> file). But,
>> > >> for backwards compatibility, we support .bom files that
>> have no such
>> > >> metadata.
>> > >>
>> > >> *## Old Behaviour (0.11.0 and Earlier)*
>> > >>
>> > >> Before we added full support and use of bundles in the
>> catalog, the
>> > >> user's .bom file was parsed and its items added to the
>> catalog. The
>> > >> raw .bom file was discarded.
>> > >>
>> > >> For upgrade/dependencies/versioning/usability reasons
>> described in
>> > >> [1,2,3], this was a bad idea.
>> > >>
>> > >>
>> > >> *## Reason the Current Behaviour is Bad!*
>> > >>
>> > >> By auto-generating bundle names, we allow users to have
>> a completely
>> > >> different mental model from what is actually happening
>> in Brooklyn.
>> > >>
>> > >> For simple cases (e.g. their .bom file only ever
>> contains one item),
>> > >> that's fine.
>> > >>
>> > >> However, it leads to surprising behaviour (and more
>> complicated
>> > >> Brooklyn code), particularly when using snapshots or
>> forced upgrade.
>> > >>
>> > >> Consider a (developer) user writing a .bom file, with
>> version
>> > >> 1.0.0-SNAPSHOT containing entities A and B. If the user
>> modifies it
>> > >> and runs `br catalog add myfile.bom` then we
>> successfully replace the
>> > >> old auto-generated bundle with this new one. However, if
>> the user
>> > >> then deletes B (so the .bom contains only A) and does
>> `catalog add`
>> > >> again, it's unclear to Brooklyn whether this is meant to
>> be the same
>> > >> .bom file. You could argue that it should be forbidden
>> (because if we
>> > >> kept the old .bom we'd end up with two different
>> versions of A, and
>> > >> deleting B would be wrong if it was a different .bom).
>> > >>
>> > >> The right thing in my opinion is to force the user to
>> have the same
>> > >> mental model as Brooklyn does: they need to include a
>> `bundle: ` line
>> > >> in their .bom file so they are explicit about what they
>> are doing.
>> > >>
>> > >> Note this does not force the user to understand
>> OSGi/java; it just
>> > >> requires them to think in terms of a "versioned bundle"
>> of catalog
>> > >> items.
>> > >>
>> > >> Aled
>> > >>
>> > >> [1] "Uploading ZIPs for a better dev workflow"
>> dev@brooklyn email
>> > thread
>> > >> [2] "Bundles in Brooklyn" dev@brooklyn email thread
>> > >> [3] "Bundles of fun" dev@brooklyn email thread
>> > >>
>> > >>
>> > >
>> >
>> >
>>
>> --
>>
>> Thomas Bouron • Senior Software Engineer @ Cloudsoft Corporation
>> • https://cloudsoft.io/
>> Github: https://github.com/tbouron
>> Twitter: https://twitter.com/eltibouron
>
> --
>
> Thomas Bouron • Senior Software Engineer @ Cloudsoft Corporation •
> https://cloudsoft.io/
> Github: https://github.com/tbouron
> Twitter: https://twitter.com/eltibouron
Re: [PROPOSAL] catalog bundle id:version mandatory in v1.0.0
Posted by Thomas Bouron <th...@cloudsoftcorp.com>.
Fair points Alex, you are absolutely right.
Although, I still think that forcing to have `bundle:` now in a bom is a
better way: It will be annoying for users but easy to fix, whereas the
alternative means that it Brooklyn **will be broken on restart/rebind**
which is a clear no-go from my point of view.
Best
On Fri, 27 Oct 2017 at 09:12 Alex Heneveld <al...@cloudsoftcorp.com>
wrote:
>
> Thinking about it I'm not convinced that breaking users blueprints is the
> best way to update their mental model. With a shift to use the CLI with
> catalog.bom in root and updating exemplar projects, and updating UI to
> reflect bundles, I expect we'll achieve this in a less disruptive way.
>
> At minimum I don't think we should make it a breaking change to try to
> force a mental model switch until _we_ have:
>
> * made catalog UI be bundle-centric (currently bundle name is shown but
> you can't navigate by bundles)
> * made composer be bundle-centric - at minimum including a bundle name in
> the template Brooklyn shows, but ideally more, allowing people to edit
> multiple resources in a bundle via the UI (else we aren't really operating
> on the new mental model)
>
> We will also need a non-trivial amount of work to update tests probably
> the majority of which use anonymous bundles and many of which test aspects
> of anonymous bundles (and we'd have to be careful in updating/fixing tests
> to identify the latter ones).
>
>
> Some halfway house measures would be to provide more obvious feedback to
> users when they install or use anonymous bundles:
>
> * CLI and UI show the name of the bundle added, with a warning if it's an
> anonymous one (user can then easily delete and release with better name)
> * UI show warnings on items from anonymous bundles
>
>
> Also maybe it's worth adding a "strict" mode to Brooklyn, where in strict
> mode this is disabled (and other things, like persisting/rebinding
> anonymous types or other deprecated features). We could even persist this
> setting so new users work in strict mode but if you're rebinding you get
> non-strict mode.
>
> Best
>
> Alex
>
>
>
> On 27/10/2017 08:16, Thomas Bouron wrote:
>
> +1, this sounds sensible to me too.
> I also vote in favor of making this a breaking change. With 1.0.0 coming,
> this is the perfect time to do it.
>
> Best.
>
> On Fri, 27 Oct 2017 at 08:06 Geoff Macartney <ge...@cloudsoft.io>
> wrote:
>
>> +1 to your suggestion Aled. Also I'd side with making it a breaking
>> change, I prefer forcing that mental model.
>>
>> On Thu, 26 Oct 2017 at 13:12 Aled Sage <al...@gmail.com> wrote:
>>
>> > Alex,
>> >
>> > I say we break it - force the user to have the correct mental model for
>> > 1.0.0!
>> >
>> > It's a simple one-line addition to fix a given .bom file. We should
>> > obviously ensure that historic persisted state continues to work.
>> >
>> > ---
>> >
>> > Also note that our deprecation warnings are too hidden. For example, if
>> > you do `br catalog add ...` then deprecation warnings will only be
>> > visible via the Brooklyn log (rather than being returned to the user of
>> > `br` or via the REST api).
>> >
>> > But that's a separate topic!
>> >
>> > Aled
>> >
>> >
>> > On 26/10/2017 12:58, Alex Heneveld wrote:
>> > >
>> > > Absolutely.
>> > >
>> > > Question is whether we should deprecate or make it a breaking change.
>> > >
>> > > Deprecating feels right, though I think it would mean we can't
>> > > actually remove until 2.0 ?
>> > >
>> > > Best
>> > > Alex
>> > >
>> > >
>> > > On 26/10/2017 12:06, Aled Sage wrote:
>> > >> Hi all,
>> > >>
>> > >> I propose we make it mandatory to specify the bundle id and version
>> > >> (currently it is optional).
>> > >>
>> > >> I think we should do this asap, before 1.0.0 is released.
>> > >>
>> > >> This is a breaking change - it will require users to add a `bundle:
>> > >> ...` line to their .bom files (if they are not supplying the metadata
>> > >> another way, such as building their project as an OSGi bundle).
>> > >>
>> > >> TL;DR: for backwards compatibility, we let users have a different
>> > >> mental model from what Brooklyn now actually does, which can lead to
>> > >> confusing behaviour when upgrading or working with snapshots.
>> > >>
>> > >> *## Current Behaviour*
>> > >>
>> > >> Currently, we'll auto-wrap things as a bundle, generating a unique
>> > >> anonymous bundle name:version if one is not supplied.
>> > >>
>> > >> This is important for users doing `br catalog add myfile.bom` or `br
>> > >> catalog add mydir/`. In both cases we automatically create an OSGi
>> > >> bundle with those contents. For that bundle's name:version, one can
>> > >> explicitly supply it (e.g. via `bundle: ...` in the .bom file). But,
>> > >> for backwards compatibility, we support .bom files that have no such
>> > >> metadata.
>> > >>
>> > >> *## Old Behaviour (0.11.0 and Earlier)*
>> > >>
>> > >> Before we added full support and use of bundles in the catalog, the
>> > >> user's .bom file was parsed and its items added to the catalog. The
>> > >> raw .bom file was discarded.
>> > >>
>> > >> For upgrade/dependencies/versioning/usability reasons described in
>> > >> [1,2,3], this was a bad idea.
>> > >>
>> > >>
>> > >> *## Reason the Current Behaviour is Bad!*
>> > >>
>> > >> By auto-generating bundle names, we allow users to have a completely
>> > >> different mental model from what is actually happening in Brooklyn.
>> > >>
>> > >> For simple cases (e.g. their .bom file only ever contains one item),
>> > >> that's fine.
>> > >>
>> > >> However, it leads to surprising behaviour (and more complicated
>> > >> Brooklyn code), particularly when using snapshots or forced upgrade.
>> > >>
>> > >> Consider a (developer) user writing a .bom file, with version
>> > >> 1.0.0-SNAPSHOT containing entities A and B. If the user modifies it
>> > >> and runs `br catalog add myfile.bom` then we successfully replace the
>> > >> old auto-generated bundle with this new one. However, if the user
>> > >> then deletes B (so the .bom contains only A) and does `catalog add`
>> > >> again, it's unclear to Brooklyn whether this is meant to be the same
>> > >> .bom file. You could argue that it should be forbidden (because if we
>> > >> kept the old .bom we'd end up with two different versions of A, and
>> > >> deleting B would be wrong if it was a different .bom).
>> > >>
>> > >> The right thing in my opinion is to force the user to have the same
>> > >> mental model as Brooklyn does: they need to include a `bundle: ` line
>> > >> in their .bom file so they are explicit about what they are doing.
>> > >>
>> > >> Note this does not force the user to understand OSGi/java; it just
>> > >> requires them to think in terms of a "versioned bundle" of catalog
>> > >> items.
>> > >>
>> > >> Aled
>> > >>
>> > >> [1] "Uploading ZIPs for a better dev workflow" dev@brooklyn email
>> > thread
>> > >> [2] "Bundles in Brooklyn" dev@brooklyn email thread
>> > >> [3] "Bundles of fun" dev@brooklyn email thread
>> > >>
>> > >>
>> > >
>> >
>> >
>>
> --
>
> Thomas Bouron • Senior Software Engineer @ Cloudsoft Corporation •
> https://cloudsoft.io/
> Github: https://github.com/tbouron
> Twitter: https://twitter.com/eltibouron
>
>
> --
Thomas Bouron • Senior Software Engineer @ Cloudsoft Corporation •
https://cloudsoft.io/
Github: https://github.com/tbouron
Twitter: https://twitter.com/eltibouron
Re: [PROPOSAL] catalog bundle id:version mandatory in v1.0.0
Posted by Alex Heneveld <al...@cloudsoftcorp.com>.
Thinking about it I'm not convinced that breaking users blueprints is
the best way to update their mental model. With a shift to use the CLI
with catalog.bom in root and updating exemplar projects, and updating UI
to reflect bundles, I expect we'll achieve this in a less disruptive way.
At minimum I don't think we should make it a breaking change to try to
force a mental model switch until _we_ have:
* made catalog UI be bundle-centric (currently bundle name is shown but
you can't navigate by bundles)
* made composer be bundle-centric - at minimum including a bundle name
in the template Brooklyn shows, but ideally more, allowing people to
edit multiple resources in a bundle via the UI (else we aren't really
operating on the new mental model)
We will also need a non-trivial amount of work to update tests probably
the majority of which use anonymous bundles and many of which test
aspects of anonymous bundles (and we'd have to be careful in
updating/fixing tests to identify the latter ones).
Some halfway house measures would be to provide more obvious feedback to
users when they install or use anonymous bundles:
* CLI and UI show the name of the bundle added, with a warning if it's
an anonymous one (user can then easily delete and release with better name)
* UI show warnings on items from anonymous bundles
Also maybe it's worth adding a "strict" mode to Brooklyn, where in
strict mode this is disabled (and other things, like
persisting/rebinding anonymous types or other deprecated features). We
could even persist this setting so new users work in strict mode but if
you're rebinding you get non-strict mode.
Best
Alex
On 27/10/2017 08:16, Thomas Bouron wrote:
> +1, this sounds sensible to me too.
> I also vote in favor of making this a breaking change. With 1.0.0
> coming, this is the perfect time to do it.
>
> Best.
>
> On Fri, 27 Oct 2017 at 08:06 Geoff Macartney
> <geoff.macartney@cloudsoft.io <ma...@cloudsoft.io>>
> wrote:
>
> +1 to your suggestion Aled. Also I'd side with making it a breaking
> change, I prefer forcing that mental model.
>
> On Thu, 26 Oct 2017 at 13:12 Aled Sage <aled.sage@gmail.com
> <ma...@gmail.com>> wrote:
>
> > Alex,
> >
> > I say we break it - force the user to have the correct mental
> model for
> > 1.0.0!
> >
> > It's a simple one-line addition to fix a given .bom file. We should
> > obviously ensure that historic persisted state continues to work.
> >
> > ---
> >
> > Also note that our deprecation warnings are too hidden. For
> example, if
> > you do `br catalog add ...` then deprecation warnings will only be
> > visible via the Brooklyn log (rather than being returned to the
> user of
> > `br` or via the REST api).
> >
> > But that's a separate topic!
> >
> > Aled
> >
> >
> > On 26/10/2017 12:58, Alex Heneveld wrote:
> > >
> > > Absolutely.
> > >
> > > Question is whether we should deprecate or make it a breaking
> change.
> > >
> > > Deprecating feels right, though I think it would mean we can't
> > > actually remove until 2.0 ?
> > >
> > > Best
> > > Alex
> > >
> > >
> > > On 26/10/2017 12:06, Aled Sage wrote:
> > >> Hi all,
> > >>
> > >> I propose we make it mandatory to specify the bundle id and
> version
> > >> (currently it is optional).
> > >>
> > >> I think we should do this asap, before 1.0.0 is released.
> > >>
> > >> This is a breaking change - it will require users to add a
> `bundle:
> > >> ...` line to their .bom files (if they are not supplying the
> metadata
> > >> another way, such as building their project as an OSGi bundle).
> > >>
> > >> TL;DR: for backwards compatibility, we let users have a different
> > >> mental model from what Brooklyn now actually does, which can
> lead to
> > >> confusing behaviour when upgrading or working with snapshots.
> > >>
> > >> *## Current Behaviour*
> > >>
> > >> Currently, we'll auto-wrap things as a bundle, generating a
> unique
> > >> anonymous bundle name:version if one is not supplied.
> > >>
> > >> This is important for users doing `br catalog add myfile.bom`
> or `br
> > >> catalog add mydir/`. In both cases we automatically create an
> OSGi
> > >> bundle with those contents. For that bundle's name:version,
> one can
> > >> explicitly supply it (e.g. via `bundle: ...` in the .bom
> file). But,
> > >> for backwards compatibility, we support .bom files that have
> no such
> > >> metadata.
> > >>
> > >> *## Old Behaviour (0.11.0 and Earlier)*
> > >>
> > >> Before we added full support and use of bundles in the
> catalog, the
> > >> user's .bom file was parsed and its items added to the
> catalog. The
> > >> raw .bom file was discarded.
> > >>
> > >> For upgrade/dependencies/versioning/usability reasons
> described in
> > >> [1,2,3], this was a bad idea.
> > >>
> > >>
> > >> *## Reason the Current Behaviour is Bad!*
> > >>
> > >> By auto-generating bundle names, we allow users to have a
> completely
> > >> different mental model from what is actually happening in
> Brooklyn.
> > >>
> > >> For simple cases (e.g. their .bom file only ever contains one
> item),
> > >> that's fine.
> > >>
> > >> However, it leads to surprising behaviour (and more complicated
> > >> Brooklyn code), particularly when using snapshots or forced
> upgrade.
> > >>
> > >> Consider a (developer) user writing a .bom file, with version
> > >> 1.0.0-SNAPSHOT containing entities A and B. If the user
> modifies it
> > >> and runs `br catalog add myfile.bom` then we successfully
> replace the
> > >> old auto-generated bundle with this new one. However, if the user
> > >> then deletes B (so the .bom contains only A) and does
> `catalog add`
> > >> again, it's unclear to Brooklyn whether this is meant to be
> the same
> > >> .bom file. You could argue that it should be forbidden
> (because if we
> > >> kept the old .bom we'd end up with two different versions of
> A, and
> > >> deleting B would be wrong if it was a different .bom).
> > >>
> > >> The right thing in my opinion is to force the user to have
> the same
> > >> mental model as Brooklyn does: they need to include a
> `bundle: ` line
> > >> in their .bom file so they are explicit about what they are
> doing.
> > >>
> > >> Note this does not force the user to understand OSGi/java; it
> just
> > >> requires them to think in terms of a "versioned bundle" of
> catalog
> > >> items.
> > >>
> > >> Aled
> > >>
> > >> [1] "Uploading ZIPs for a better dev workflow" dev@brooklyn email
> > thread
> > >> [2] "Bundles in Brooklyn" dev@brooklyn email thread
> > >> [3] "Bundles of fun" dev@brooklyn email thread
> > >>
> > >>
> > >
> >
> >
>
> --
>
> Thomas Bouron • Senior Software Engineer @ Cloudsoft Corporation •
> https://cloudsoft.io/
> Github: https://github.com/tbouron
> Twitter: https://twitter.com/eltibouron
Re: [PROPOSAL] catalog bundle id:version mandatory in v1.0.0
Posted by Thomas Bouron <th...@cloudsoftcorp.com>.
+1, this sounds sensible to me too.
I also vote in favor of making this a breaking change. With 1.0.0 coming,
this is the perfect time to do it.
Best.
On Fri, 27 Oct 2017 at 08:06 Geoff Macartney <ge...@cloudsoft.io>
wrote:
> +1 to your suggestion Aled. Also I'd side with making it a breaking
> change, I prefer forcing that mental model.
>
> On Thu, 26 Oct 2017 at 13:12 Aled Sage <al...@gmail.com> wrote:
>
> > Alex,
> >
> > I say we break it - force the user to have the correct mental model for
> > 1.0.0!
> >
> > It's a simple one-line addition to fix a given .bom file. We should
> > obviously ensure that historic persisted state continues to work.
> >
> > ---
> >
> > Also note that our deprecation warnings are too hidden. For example, if
> > you do `br catalog add ...` then deprecation warnings will only be
> > visible via the Brooklyn log (rather than being returned to the user of
> > `br` or via the REST api).
> >
> > But that's a separate topic!
> >
> > Aled
> >
> >
> > On 26/10/2017 12:58, Alex Heneveld wrote:
> > >
> > > Absolutely.
> > >
> > > Question is whether we should deprecate or make it a breaking change.
> > >
> > > Deprecating feels right, though I think it would mean we can't
> > > actually remove until 2.0 ?
> > >
> > > Best
> > > Alex
> > >
> > >
> > > On 26/10/2017 12:06, Aled Sage wrote:
> > >> Hi all,
> > >>
> > >> I propose we make it mandatory to specify the bundle id and version
> > >> (currently it is optional).
> > >>
> > >> I think we should do this asap, before 1.0.0 is released.
> > >>
> > >> This is a breaking change - it will require users to add a `bundle:
> > >> ...` line to their .bom files (if they are not supplying the metadata
> > >> another way, such as building their project as an OSGi bundle).
> > >>
> > >> TL;DR: for backwards compatibility, we let users have a different
> > >> mental model from what Brooklyn now actually does, which can lead to
> > >> confusing behaviour when upgrading or working with snapshots.
> > >>
> > >> *## Current Behaviour*
> > >>
> > >> Currently, we'll auto-wrap things as a bundle, generating a unique
> > >> anonymous bundle name:version if one is not supplied.
> > >>
> > >> This is important for users doing `br catalog add myfile.bom` or `br
> > >> catalog add mydir/`. In both cases we automatically create an OSGi
> > >> bundle with those contents. For that bundle's name:version, one can
> > >> explicitly supply it (e.g. via `bundle: ...` in the .bom file). But,
> > >> for backwards compatibility, we support .bom files that have no such
> > >> metadata.
> > >>
> > >> *## Old Behaviour (0.11.0 and Earlier)*
> > >>
> > >> Before we added full support and use of bundles in the catalog, the
> > >> user's .bom file was parsed and its items added to the catalog. The
> > >> raw .bom file was discarded.
> > >>
> > >> For upgrade/dependencies/versioning/usability reasons described in
> > >> [1,2,3], this was a bad idea.
> > >>
> > >>
> > >> *## Reason the Current Behaviour is Bad!*
> > >>
> > >> By auto-generating bundle names, we allow users to have a completely
> > >> different mental model from what is actually happening in Brooklyn.
> > >>
> > >> For simple cases (e.g. their .bom file only ever contains one item),
> > >> that's fine.
> > >>
> > >> However, it leads to surprising behaviour (and more complicated
> > >> Brooklyn code), particularly when using snapshots or forced upgrade.
> > >>
> > >> Consider a (developer) user writing a .bom file, with version
> > >> 1.0.0-SNAPSHOT containing entities A and B. If the user modifies it
> > >> and runs `br catalog add myfile.bom` then we successfully replace the
> > >> old auto-generated bundle with this new one. However, if the user
> > >> then deletes B (so the .bom contains only A) and does `catalog add`
> > >> again, it's unclear to Brooklyn whether this is meant to be the same
> > >> .bom file. You could argue that it should be forbidden (because if we
> > >> kept the old .bom we'd end up with two different versions of A, and
> > >> deleting B would be wrong if it was a different .bom).
> > >>
> > >> The right thing in my opinion is to force the user to have the same
> > >> mental model as Brooklyn does: they need to include a `bundle: ` line
> > >> in their .bom file so they are explicit about what they are doing.
> > >>
> > >> Note this does not force the user to understand OSGi/java; it just
> > >> requires them to think in terms of a "versioned bundle" of catalog
> > >> items.
> > >>
> > >> Aled
> > >>
> > >> [1] "Uploading ZIPs for a better dev workflow" dev@brooklyn email
> > thread
> > >> [2] "Bundles in Brooklyn" dev@brooklyn email thread
> > >> [3] "Bundles of fun" dev@brooklyn email thread
> > >>
> > >>
> > >
> >
> >
>
--
Thomas Bouron • Senior Software Engineer @ Cloudsoft Corporation •
https://cloudsoft.io/
Github: https://github.com/tbouron
Twitter: https://twitter.com/eltibouron
Re: [PROPOSAL] catalog bundle id:version mandatory in v1.0.0
Posted by Geoff Macartney <ge...@cloudsoft.io>.
+1 to your suggestion Aled. Also I'd side with making it a breaking
change, I prefer forcing that mental model.
On Thu, 26 Oct 2017 at 13:12 Aled Sage <al...@gmail.com> wrote:
> Alex,
>
> I say we break it - force the user to have the correct mental model for
> 1.0.0!
>
> It's a simple one-line addition to fix a given .bom file. We should
> obviously ensure that historic persisted state continues to work.
>
> ---
>
> Also note that our deprecation warnings are too hidden. For example, if
> you do `br catalog add ...` then deprecation warnings will only be
> visible via the Brooklyn log (rather than being returned to the user of
> `br` or via the REST api).
>
> But that's a separate topic!
>
> Aled
>
>
> On 26/10/2017 12:58, Alex Heneveld wrote:
> >
> > Absolutely.
> >
> > Question is whether we should deprecate or make it a breaking change.
> >
> > Deprecating feels right, though I think it would mean we can't
> > actually remove until 2.0 ?
> >
> > Best
> > Alex
> >
> >
> > On 26/10/2017 12:06, Aled Sage wrote:
> >> Hi all,
> >>
> >> I propose we make it mandatory to specify the bundle id and version
> >> (currently it is optional).
> >>
> >> I think we should do this asap, before 1.0.0 is released.
> >>
> >> This is a breaking change - it will require users to add a `bundle:
> >> ...` line to their .bom files (if they are not supplying the metadata
> >> another way, such as building their project as an OSGi bundle).
> >>
> >> TL;DR: for backwards compatibility, we let users have a different
> >> mental model from what Brooklyn now actually does, which can lead to
> >> confusing behaviour when upgrading or working with snapshots.
> >>
> >> *## Current Behaviour*
> >>
> >> Currently, we'll auto-wrap things as a bundle, generating a unique
> >> anonymous bundle name:version if one is not supplied.
> >>
> >> This is important for users doing `br catalog add myfile.bom` or `br
> >> catalog add mydir/`. In both cases we automatically create an OSGi
> >> bundle with those contents. For that bundle's name:version, one can
> >> explicitly supply it (e.g. via `bundle: ...` in the .bom file). But,
> >> for backwards compatibility, we support .bom files that have no such
> >> metadata.
> >>
> >> *## Old Behaviour (0.11.0 and Earlier)*
> >>
> >> Before we added full support and use of bundles in the catalog, the
> >> user's .bom file was parsed and its items added to the catalog. The
> >> raw .bom file was discarded.
> >>
> >> For upgrade/dependencies/versioning/usability reasons described in
> >> [1,2,3], this was a bad idea.
> >>
> >>
> >> *## Reason the Current Behaviour is Bad!*
> >>
> >> By auto-generating bundle names, we allow users to have a completely
> >> different mental model from what is actually happening in Brooklyn.
> >>
> >> For simple cases (e.g. their .bom file only ever contains one item),
> >> that's fine.
> >>
> >> However, it leads to surprising behaviour (and more complicated
> >> Brooklyn code), particularly when using snapshots or forced upgrade.
> >>
> >> Consider a (developer) user writing a .bom file, with version
> >> 1.0.0-SNAPSHOT containing entities A and B. If the user modifies it
> >> and runs `br catalog add myfile.bom` then we successfully replace the
> >> old auto-generated bundle with this new one. However, if the user
> >> then deletes B (so the .bom contains only A) and does `catalog add`
> >> again, it's unclear to Brooklyn whether this is meant to be the same
> >> .bom file. You could argue that it should be forbidden (because if we
> >> kept the old .bom we'd end up with two different versions of A, and
> >> deleting B would be wrong if it was a different .bom).
> >>
> >> The right thing in my opinion is to force the user to have the same
> >> mental model as Brooklyn does: they need to include a `bundle: ` line
> >> in their .bom file so they are explicit about what they are doing.
> >>
> >> Note this does not force the user to understand OSGi/java; it just
> >> requires them to think in terms of a "versioned bundle" of catalog
> >> items.
> >>
> >> Aled
> >>
> >> [1] "Uploading ZIPs for a better dev workflow" dev@brooklyn email
> thread
> >> [2] "Bundles in Brooklyn" dev@brooklyn email thread
> >> [3] "Bundles of fun" dev@brooklyn email thread
> >>
> >>
> >
>
>
Re: [PROPOSAL] catalog bundle id:version mandatory in v1.0.0
Posted by Aled Sage <al...@gmail.com>.
Alex,
I say we break it - force the user to have the correct mental model for
1.0.0!
It's a simple one-line addition to fix a given .bom file. We should
obviously ensure that historic persisted state continues to work.
---
Also note that our deprecation warnings are too hidden. For example, if
you do `br catalog add ...` then deprecation warnings will only be
visible via the Brooklyn log (rather than being returned to the user of
`br` or via the REST api).
But that's a separate topic!
Aled
On 26/10/2017 12:58, Alex Heneveld wrote:
>
> Absolutely.
>
> Question is whether we should deprecate or make it a breaking change.
>
> Deprecating feels right, though I think it would mean we can't
> actually remove until 2.0 ?
>
> Best
> Alex
>
>
> On 26/10/2017 12:06, Aled Sage wrote:
>> Hi all,
>>
>> I propose we make it mandatory to specify the bundle id and version
>> (currently it is optional).
>>
>> I think we should do this asap, before 1.0.0 is released.
>>
>> This is a breaking change - it will require users to add a `bundle:
>> ...` line to their .bom files (if they are not supplying the metadata
>> another way, such as building their project as an OSGi bundle).
>>
>> TL;DR: for backwards compatibility, we let users have a different
>> mental model from what Brooklyn now actually does, which can lead to
>> confusing behaviour when upgrading or working with snapshots.
>>
>> *## Current Behaviour*
>>
>> Currently, we'll auto-wrap things as a bundle, generating a unique
>> anonymous bundle name:version if one is not supplied.
>>
>> This is important for users doing `br catalog add myfile.bom` or `br
>> catalog add mydir/`. In both cases we automatically create an OSGi
>> bundle with those contents. For that bundle's name:version, one can
>> explicitly supply it (e.g. via `bundle: ...` in the .bom file). But,
>> for backwards compatibility, we support .bom files that have no such
>> metadata.
>>
>> *## Old Behaviour (0.11.0 and Earlier)*
>>
>> Before we added full support and use of bundles in the catalog, the
>> user's .bom file was parsed and its items added to the catalog. The
>> raw .bom file was discarded.
>>
>> For upgrade/dependencies/versioning/usability reasons described in
>> [1,2,3], this was a bad idea.
>>
>>
>> *## Reason the Current Behaviour is Bad!*
>>
>> By auto-generating bundle names, we allow users to have a completely
>> different mental model from what is actually happening in Brooklyn.
>>
>> For simple cases (e.g. their .bom file only ever contains one item),
>> that's fine.
>>
>> However, it leads to surprising behaviour (and more complicated
>> Brooklyn code), particularly when using snapshots or forced upgrade.
>>
>> Consider a (developer) user writing a .bom file, with version
>> 1.0.0-SNAPSHOT containing entities A and B. If the user modifies it
>> and runs `br catalog add myfile.bom` then we successfully replace the
>> old auto-generated bundle with this new one. However, if the user
>> then deletes B (so the .bom contains only A) and does `catalog add`
>> again, it's unclear to Brooklyn whether this is meant to be the same
>> .bom file. You could argue that it should be forbidden (because if we
>> kept the old .bom we'd end up with two different versions of A, and
>> deleting B would be wrong if it was a different .bom).
>>
>> The right thing in my opinion is to force the user to have the same
>> mental model as Brooklyn does: they need to include a `bundle: ` line
>> in their .bom file so they are explicit about what they are doing.
>>
>> Note this does not force the user to understand OSGi/java; it just
>> requires them to think in terms of a "versioned bundle" of catalog
>> items.
>>
>> Aled
>>
>> [1] "Uploading ZIPs for a better dev workflow" dev@brooklyn email thread
>> [2] "Bundles in Brooklyn" dev@brooklyn email thread
>> [3] "Bundles of fun" dev@brooklyn email thread
>>
>>
>
Re: [PROPOSAL] catalog bundle id:version mandatory in v1.0.0
Posted by Alex Heneveld <al...@cloudsoftcorp.com>.
Absolutely.
Question is whether we should deprecate or make it a breaking change.
Deprecating feels right, though I think it would mean we can't actually
remove until 2.0 ?
Best
Alex
On 26/10/2017 12:06, Aled Sage wrote:
> Hi all,
>
> I propose we make it mandatory to specify the bundle id and version
> (currently it is optional).
>
> I think we should do this asap, before 1.0.0 is released.
>
> This is a breaking change - it will require users to add a `bundle:
> ...` line to their .bom files (if they are not supplying the metadata
> another way, such as building their project as an OSGi bundle).
>
> TL;DR: for backwards compatibility, we let users have a different
> mental model from what Brooklyn now actually does, which can lead to
> confusing behaviour when upgrading or working with snapshots.
>
> *## Current Behaviour*
>
> Currently, we'll auto-wrap things as a bundle, generating a unique
> anonymous bundle name:version if one is not supplied.
>
> This is important for users doing `br catalog add myfile.bom` or `br
> catalog add mydir/`. In both cases we automatically create an OSGi
> bundle with those contents. For that bundle's name:version, one can
> explicitly supply it (e.g. via `bundle: ...` in the .bom file). But,
> for backwards compatibility, we support .bom files that have no such
> metadata.
>
> *## Old Behaviour (0.11.0 and Earlier)*
>
> Before we added full support and use of bundles in the catalog, the
> user's .bom file was parsed and its items added to the catalog. The
> raw .bom file was discarded.
>
> For upgrade/dependencies/versioning/usability reasons described in
> [1,2,3], this was a bad idea.
>
>
> *## Reason the Current Behaviour is Bad!*
>
> By auto-generating bundle names, we allow users to have a completely
> different mental model from what is actually happening in Brooklyn.
>
> For simple cases (e.g. their .bom file only ever contains one item),
> that's fine.
>
> However, it leads to surprising behaviour (and more complicated
> Brooklyn code), particularly when using snapshots or forced upgrade.
>
> Consider a (developer) user writing a .bom file, with version
> 1.0.0-SNAPSHOT containing entities A and B. If the user modifies it
> and runs `br catalog add myfile.bom` then we successfully replace the
> old auto-generated bundle with this new one. However, if the user then
> deletes B (so the .bom contains only A) and does `catalog add` again,
> it's unclear to Brooklyn whether this is meant to be the same .bom
> file. You could argue that it should be forbidden (because if we kept
> the old .bom we'd end up with two different versions of A, and
> deleting B would be wrong if it was a different .bom).
>
> The right thing in my opinion is to force the user to have the same
> mental model as Brooklyn does: they need to include a `bundle: ` line
> in their .bom file so they are explicit about what they are doing.
>
> Note this does not force the user to understand OSGi/java; it just
> requires them to think in terms of a "versioned bundle" of catalog items.
>
> Aled
>
> [1] "Uploading ZIPs for a better dev workflow" dev@brooklyn email thread
> [2] "Bundles in Brooklyn" dev@brooklyn email thread
> [3] "Bundles of fun" dev@brooklyn email thread
>
>