Commons refactoring - reloaded [was: Once more: Commons refactoring and releasing]

[Manfred Geiler <ma...@gmail.com>]

I recollected all the issues, ideas, and feedback and tried to
summarize them (from my personal POV):

==========================================
Here is a "management summary" of what we could/should end with:
 * A "myfaces-shared" project, housing all MyFaces-specific classes
shared between impl and the MyFaces component libs.
 * A "myfaces-commons" project with helpers, utils and goodies that
are useful for the whole JSF community.
 * myfaces-shared itself will never be released and none of the
MyFaces subprojects will have a direct dependency on it.
Alternatively, every project that needs shared classes will be
provided a custom shared lib with private namespace, so that shared
classes of different versions won't clash during runtime.
 * myfaces-commons will have a well defined and stable API and have
it's own release cycle once in a bright future.

==========================================
And here are the details:
 * We create a new "shared" SVN module (artifactId = "myfaces-shared")
that starts off with all classes currently in commons. Namespace will
be "org.apache.myfaces.shared.*"

 * myfaces-shared will have sub-modules that represent the custom
dependency libs with private namespace for each MyFaces subproject
that needs shared classes (only impl and tomahawk so far). All (=both)
artifacts will automatically be created from the same source that sits
in the Maven parent module "myfaces-shared:
  - Artifact "myfaces-shared-impl" with namespace
"org.apache.myfaces.impl.shared.*"
  - Artifact "myfaces-shared-tomahawk" with namespace
"org.apache.myfaces.tomahawk.shared.*"

 * We flush everything from "commons" and plan to refill it with real
commons classes - ie. classes with public interest that make sense
outside the MyFaces scope as well AND which have a well designed and
stable API. To achieve this the new "commons" subproject will be
divided into an api and an impl part (as suggested by the John and
Adam): myfaces-commons-api-x.y.z.jar and
myfaces-commons-impl-x.y.z.jar

==========================================
And now the "How?":

Sean, anything that speaks against creating a shared SVN module in
trunk right now?

I think we could do the following to get our core released ASAP:
1. Forget about already released myfaces-commons-1.1.2.jar (we
"unrelease" it somehow) and go back to the start.
2. Create the "shared" SVN module with the two submodules
"shared-impl" and "shared-tomahawk".
3. Move everything from commons to shared and change namespace to
"org.apache.myfaces.shared.*".
4. Build the two dependency libs myfaces-shared-impl and
myfaces-shared-tomahawk.
5. Refactor impl to use the org.apache.myfaces.impl.shared.* classes
6. Refactor tomahawk to use the org.apache.myfaces.tomahawk.shared.* classes

At this point we are ready to start the (now really independent!)
release processes for impl-1.1.2 and tomahawk-1.1.2

Thougths?
Please consider carefully. IMO this all sounds more complicated than
it really is.
I know there is some pressure for the release. And many of you will
have the feeling that it's better to release fast and do massive
refactoring afterwards. The point is: once we have an official core
release out in the wild that dependes on an official commons release,
the chance for doing this all without "collateral damage" (oh, I hate
this term) is gone.


Manfred



On 2/22/06, Sean Schofield <se...@gmail.com> wrote:
> Now that I have thought about Manfred's proposal its starting to make
> more sense to me.  Here is my revised proposal.  It will allow us to
> make progress on this and still defer the final decision for several
> days.
>
> 1.) Create a "shared" subproject.  Leave the trunk empty and copy the
> existing commons code to a new 2.0 branch.
>
> 2.) Refactor the code in the shared branch to org.apache.myfaces.shared
>
> 3.) Create an shared-impl project beneath the shared subproject.
> Inside this dir will be a POM that will take care of creating the new
> myfaces-shared-impl.jar artifact  Use maven trickery to search and
> replace so that refs are now org.apache.myfaces.shared.impl
>
> 4.) Publish the new myfaces-shared-impl.jar as a 2.0.0-SNAPSHOT
>
> 5.) Refactor the current *branch* of the core to use the new snapshot.
>  Tweak the maven build so that it explodes the snapshot jar and dumps
> the classes into the target/classes.  Resulting myfaces-impl.jar now
> has its own "frozen snapshot" of the shared code built in.
>
> This will allow Manfred to procede without delay and we still have
> time to debate the merits of this approach.  If we decide to vote +1
> to this then we would move the commons trunk to the new shared trunk
> and retire the commons subproject (until we have a true commons
> someday.)  I believe this will allow us to eventually merge the branch
> down to the trunk even though we have renamed everything.  Ideally we
> make little to no changes on the commons trunk while this is going on.
>
> Of course tomahawk trunk would then be refactored to use the new
> shared package names.
>
> I have lots more ideas/questions but I need to head to my day job.  I
> do think that we should consider resolving this ASAP and before the
> core release.  Lets get this right so we don't have to introduce a
> commons.jar
>
> Sean
>
> On 2/22/06, Sean Schofield <se...@gmail.com> wrote:
> > This is a really big issue to wrap our collective heads around.  Maybe
> > we should focus on the immediate problem first?  The immediate
> > problem, as I see it, is that we are about to release the core and it
> > has shared code that will potentially conflict with the same shared
> > code in tomahawk.
> >
> > It will be easier (for me) at least if we limit our discussion to this
> > unless the potential solution being discussed would make it much
> > harder down the line to do some of these long run ideas.
> >
> > Sean
> >
> > On 2/22/06, Stan Silvert <st...@jboss.com> wrote:
> > > > Once our refactoring of commons classes into namespace
> > > > org.apache.myfaces.commons.* is done we can easily change namespace
> > > > for inlining by doing String search and replace on source level:
> > > > replace "org.apache.myfaces.commons" by
> > > > "org.apache.myfaces.impl-commons" (or alike)
> > > > I already have a working proof-of-concept prototype on my local disk,
> > > > but we need the org.apache.myfaces.* --> org.apache.myfaces.commons.*
> > > > refactoring first.
> > > >
> > > > Manfred
> > >
> > > I don't think that will quite do it.  You still have a versioning
> > > problem.
> > >
> > > As I understand it, this will meant that commons doesn't have a standard
> > > release cycle.  Without a standard release, the commons API would be in
> > > constant flux.
> > >
> > > At the very least, you would have to tag commons every time you do a
> > > release of a project that relies on it.  This has its problems too.
> > >
> > > (Sorry for the length of this :-) )
> > > Suppose there is a method Foo.foo(StringBuffer s) in commons, written by
> > > a developer in project A.  However, this developer doesn't consider this
> > > to be a stable API.  He's still working things out.
> > >
> > > The developer in Project B likes the Foo.foo() method and decides to use
> > > it in 1.0.
> > >
> > > Project B 1.0 is released.
> > >
> > > The Project A developer decides that passing in a mutable object is
> > > dangerous, so he changes it to Foo.foo(String s).
> > >
> > > Now Project B relies on a method that no longer exists.  In fact, he was
> > > even relying on the mutability of s.  This is generally a bad thing to
> > > do, but for some reason, it makes sense for Project B.
> > >
> > > So what does he do if he needs to fix something in a patch branch?  He
> > > can check out the tagged version of commons, but what if he needs to
> > > patch commons itself?  Now he's stuck.
> > >
> > > The more I think about the weird scenarios, the more I think that
> > > commons needs its own stable release.
> > >
> > > Stan
> > >
> > > >
> > > >
> > > > On 2/22/06, Stan Silvert <st...@jboss.com> wrote:
> > > > > > To reduce the risk of version conflicts and to make the release
> > > cycle
> > > > > > of core and tomahawk really independent, the shared classes should
> > > not
> > > > > > be released as JAR, but should automatically be repackaged and
> > > > > > "inlined" into impl, tomahawk, tobago, etc.
> > > > > >
> > > > > > Thoughts?
> > > > > >
> > > > > > Manfred
> > > > >
> > > > > Interesting idea.  Do you know of a tool that can easily pull this
> > > off?
> > > > >
> > > > > Stan
> > > > >
> > >
> >
>

Re: Commons refactoring - reloaded [was: Once more: Commons refactoring and releasing]

[Sean Schofield <se...@gmail.com>]

Yes that makes more sense.  I created the svn branch for tomahawk.  I
started the refactoring but I didn't make much progress so feel free
to start fresh.  There are 3 classes in the core branch that are now
in shared and the core since they were moved to shared after the core
branch (see MYFACES-1112.)  I think those can just be dropped
outright.

The refactoring will be a pain because both JBuilder and Idea want to
rename the package in all of the modules and not just commons.

Please do all of the refactoring on the branches for tomahawk and core
and in the new shared module so we don't get messed up.

Good luck.

Sean

Re: Commons refactoring - reloaded [was: Once more: Commons refactoring and releasing]

[Manfred Geiler <ma...@gmail.com>]

On 2/23/06, Sean Schofield <se...@gmail.com> wrote:
> >  * myfaces-shared will have sub-modules that represent the custom
> > dependency libs with private namespace for each MyFaces subproject
> > that needs shared classes (only impl and tomahawk so far). All (=both)
> > artifacts will automatically be created from the same source that sits
> > in the Maven parent module "myfaces-shared:
> >   - Artifact "myfaces-shared-impl" with namespace
> > "org.apache.myfaces.impl.shared.*"
> >   - Artifact "myfaces-shared-tomahawk" with namespace
> > "org.apache.myfaces.tomahawk.shared.*"
>
> Is it accurate to say shared will never be released? I know we won't
> make release announcments or include it in a zip but it has to be
> released for maven purposes. I just wanted to clarify that.

Ok, here's the wording how I would understand it in Maven sphere:
 install = put it into the local repository
 deploy = put it into a remote repository - either corporate or public
(ibiblio et al.)
 release = assembly, announce and ship it within a zip archive

So, using these wordings it is accurate to say:
 Yes, they will be installed locally
 Yes, they would be deployed on ibiblio (so that people are able to
build impl or tomahawk from source withing having myfaces-shared on
their disk)
 No, they will never be shipped with any assembly

Does that make it more accurate?
;-)

Manfred

Re: Commons refactoring - reloaded [was: Once more: Commons refactoring and releasing]

[Sean Schofield <se...@gmail.com>]

>  * myfaces-shared will have sub-modules that represent the custom
> dependency libs with private namespace for each MyFaces subproject
> that needs shared classes (only impl and tomahawk so far). All (=both)
> artifacts will automatically be created from the same source that sits
> in the Maven parent module "myfaces-shared:
>   - Artifact "myfaces-shared-impl" with namespace
> "org.apache.myfaces.impl.shared.*"
>   - Artifact "myfaces-shared-tomahawk" with namespace
> "org.apache.myfaces.tomahawk.shared.*"

Is it accurate to say shared will never be released? I know we won't
make release announcments or include it in a zip but it has to be
released for maven purposes. I just wanted to clarify that.

>  * We flush everything from "commons" and plan to refill it with real
> commons classes - ie. classes with public interest that make sense
> outside the MyFaces scope as well AND which have a well designed and
> stable API. To achieve this the new "commons" subproject will be
> divided into an api and an impl part (as suggested by the John and
> Adam): myfaces-commons-api-x.y.z.jar and
> myfaces-commons-impl-x.y.z.jar

Yes agreed.  I would take it one step further and remove the commons
website and module for now.  In order to minimize confusion I also
suggest we do *not* have a shared tab for the website.

> Sean, anything that speaks against creating a shared SVN module in
> trunk right now?

I guess we could make it a trunk just as easily as a branch.  SVN will
allow us to merge between commons trunk and the shared trunk while
things are in development (just as easy as merging between trunk and
branch.)  I do strongly urge that people not change anything that
requires a commons/shared change while this is going on.  Whatever it
is, it can wait!  That will make our lives much simpler.

> I think we could do the following to get our core released ASAP:
> 1. Forget about already released myfaces-commons-1.1.2.jar (we
> "unrelease" it somehow) and go back to the start.

Just ignore it.  Eventually it will be replaced by a more meaningful
2.0 release.  I advise against "unreleasing"

> 2. Create the "shared" SVN module with the two submodules
> "shared-impl" and "shared-tomahawk".

Agreed.  The bulk of the code sits in the top level right?  I'm still
a little confused about the maven details.  Maybe another post
explaining this?

> 3. Move everything from commons to shared and change namespace to
> "org.apache.myfaces.shared.*".

Yes.  I will do the svn move for you now.  This doesn't hurt to do now
while we discuss.

> 4. Build the two dependency libs myfaces-shared-impl and
> myfaces-shared-tomahawk.
> 5. Refactor impl to use the org.apache.myfaces.impl.shared.* classes
> 6. Refactor tomahawk to use the org.apache.myfaces.tomahawk.shared.* classes

+1

> At this point we are ready to start the (now really independent!)
> release processes for impl-1.1.2 and tomahawk-1.1.2

Yay!

> Thougths?
> Please consider carefully. IMO this all sounds more complicated than
> it really is.
> I know there is some pressure for the release. And many of you will
> have the feeling that it's better to release fast and do massive
> refactoring afterwards. The point is: once we have an official core
> release out in the wild that dependes on an official commons release,
> the chance for doing this all without "collateral damage" (oh, I hate
> this term) is gone.

You are absolutely right that we should not release until this is
addressed.  We don't want all of the confusion of introducing users to
commons, then take it away, then give it back except now its something
new!  Lets focus on this exclusively the next few days and get it
done.  I'd also like to hear from Simon, John and some of the others
who have expressed an interest in this area before.

> Manfred

Sean