Describe Tuscany/TuscanyJava/SDOJavaReleaseSteps/RoughNotes here. here are draft asf guidlines http://incubator.apache.org/guides/releasemanagement.html

here's how axis2 do it http://wiki.apache.org/ws/FrontPage/Axis2C/releases/steps

heres an rss feed of my todo list that can be used to harvest info in a release postmortem http://www.airset.com/syndicate/VoWYwSHvNutI/lists.xml

making the source distribution

manual task -- see discussion at http://www.mail-archive.com/tuscany-dev%40ws.apache.org/msg08313.html

code streams

Make a branch with svn copy while preparing the release, then make a tag in order to cut the final distribution

making the branch

command line approach, first set variable SVN_EDITOR to catch output of command then e.g.

svn copy https://svn.apache.org/repos/asf/incubator/tuscany/sandbox/kgoodson/testRoot  https://svn.apache.org/repos/asf/incubator/tuscany/sandbox/kgoodson/branches/1.0/testRoot

I got an odd message in the $SVN_EDITOR of the form

--This line, and those below, will be ignored--

A    https://svn.apache.org/repos/asf/incubator/tuscany/sandbox/kgoodson/branches/1.0/testRoot/testRoot

and was given the options to abort, continue or edit --- when I had the confidence to try continue, it all worked.

I assembled the branch by creating folders spec and distribution, then doing three svn copy commands, one each for distribution/sdo spec/sdo and sdo (at the end of this we were at revision 449978 with no chnages having happened to the main trunk sdo code in during the set of copy commands)

Appendix: Some Raw Command Dumps From the RC1a src distro creation process

mkdir RC1a
cd RC1a
mkdir spec
cd spec
svn export https://svn.apache.org/repos/asf/incubator/tuscany/java/spec/sdo
cd ..
svn export https://svn.apache.org/repos/asf/incubator/tuscany/java/sdo
356     tar -czf sdo-1.0-incubator-M2-RC1a-src.tgz .
357     ls -l
358     mv sdo-1.0-incubator-M2-SNAPSHOT-src.tgz ../RC1a
360     cd ../RC1a
...
366     gpg --armor --output sdo-1.0-incubator-M2-SNAPSHOT-src.tgz.asc --detach-sig sdo-1.0-incubator-M2-SNAPSHOT-src.tgz
367     md5sums sdo-1.0-incubator-M2-SNAPSHOT-src.tgz > sdo-1.0-incubator-M2-SNAPSHOT-src.tgz.md5

A reelvant IRC chat that needs distilling

lresende>       jboynes: yt ?
        <jboynes>       yep
        <lresende>      should i start doing a RC for DAS simmilar to what kgoodson did for SDO ?
        <lresende>      also, do i have to do anything special to tell das to compile using the sdo rc1a ? that's how i should do it, right ?
        |<--    isilval has left irc.freenode.net ("Trillian (http://www.ceruleanstudios.com")
        <jboynes>       re RC - yes if you're ready
        <jboynes>       re the SDO version
        <jboynes>       no, the version is defined in the pom.xml in das
        <jboynes>       <dependency>
        <jboynes>       <groupId>org.apache.tuscany.sdo</groupId>
        <jboynes>       <artifactId>tuscany-sdo-impl</artifactId>
        <jboynes>       <version>1.0-incubator-M2-SNAPSHOT</version>
        <jboynes>       <scope>compile</scope>
        <jboynes>       </dependency>
        <jboynes>       when SDO releases and the copies hit the repo then that's when you would change that version
        <lresende>      i see
        <kgoodson>      how do we switch away from SNAPSHOT? is that a one line project wide change? or do we have to do that on a per sub-project basis?
        <lresende>      i think it's per-subproject
        <jboynes>       it's a little more complex unfortnately
        <kgoodson>      ok, that's something i have yet to do
        <jboynes>       yeah (don't do that until you tag)
        <kgoodson>      fine
        <jboynes>       getting different versions of non-SNAPSHOT artifacts in a repo really messes maven up
        <lresende>      and to create a branch, i'll do a svn copy(or export) and create a patch ?
        <jboynes>       svn copy
        <jboynes>       can't really patch that - we need a committer to handle it
        <jboynes>       back to changing versions :)
        <lresende>      k, will work on this today
        <jboynes>       the first thing to address is any <dependencies> that reference snapshots
        <jboynes>       they should all be replaced with references to non-SNAPSHOT versions
        <kgoodson>      i can do some svn copy stuff for you, but i may not be available for you when you want me
        <jboynes>       that is for external dependencies
        <jboynes>       e.g. emf, axis etc
        <jboynes>       external being stuff that is not in /your/ release
        <jboynes>       so e.g. when SDO releases, das would replace it's snapshot dependency on SDO with a versioned one
        <jboynes>       the other "external" dependency you have is on the parent POM
        <jboynes>       so before we do anything we need to release pom/parent
        <jboynes>       as version 1
        <jboynes>       (it's not using dot notation just an incremental counter)
        <jboynes>       and then update the root <parent> element to use it
        <lresende>      kgoodson: thanks, i'll let you know when i'm ready for that (either here or on the dev-list)
        <kgoodson>      jboynes, i'm not sure i understand the last instruction, can you clarify please
        <jboynes>       in sdo/pom.xml you have:
        <jboynes>       <parent>
        <jboynes>       <groupId>org.apache.tuscany</groupId>
        <jboynes>       <artifactId>parent</artifactId>
        <jboynes>       <version>1-incubator-SNAPSHOT</version>
        <jboynes>       </parent>
        <jboynes>       that can't be a SNAPSHOT
        <kgoodson>      perfect, thanks
        <jboynes>       i.e. you have a dependency on an external artifact (through the parent not a <dependency>)
        <jboynes>       so, we need to release the common parent pom before we can release sdo
        <kgoodson>      fine
        <jboynes>       I have tried to reduce the number of places versions are defined
        <jboynes>       e.g. in sdo/pom.xml there is a common property that defines the emfVersion
        <jboynes>       so you should only need to change that once

And another

        <kgoodson>      jboynes, you were looking for me yesterday evening
        <jboynes>       yeah
        <jboynes>       was going to ping you on upgrading EMF
        <jboynes>       I went and did it anyway :)
        <kgoodson>      ok, great, i saw your tuscany-dev note and responded, but didn't see the IRC ping
        <jboynes>       I didn't make the change in the branch
        <kgoodson>      ok, i can do that
        <jboynes>       we also need to tag das for lresende
        <jboynes>       what do you think about the samples?
        <kgoodson>      so to check, we are tagging now, yes? So if a tag is pretty imutable, how do we deal with comments on the release?
        <kgoodson>      in what way? (samples)
        <jboynes>       should we move them?
        <jboynes>       it's really an issue for the list
        <kgoodson>      i think moving could be good, but i'm not sure of the risks (e.g. documentation that has http://svn style links into the repository. And to make one tree we would also have to move the spec/sdo to sdo/spec
        <jboynes>       re spec, IMO that should be separate
        <jboynes>       at least, that's the case for SCA
        <kgoodson>      ok, so i'm not sure of the value of moving anything unless we move everything, becuase the main motivation for me is to remove the manual steps from creating the source distribution branch/tag
        <kgoodson>      i got feedback from the user list that one source distro was wanted, with spec and impl together
        <jboynes>       that's what I mean - are the spec's part of the Tuscany distro
        <kgoodson>      we'll we kind of ship our own third party dependency, but when I cut RC1 is caused confusion, creating two archives
        <kgoodson>      s/we'll/well/
        <jboynes>       what was the confusion?
        <jboynes>       as in, it seems to make sense to me - one spec, one impl
        <kgoodson>      so one user doth not a straw poll make, but I can see the point that because these two archives come from the same project its kind of off to see the source split into two
        <jboynes>       the spec an be used by many people
        <kgoodson>      ok, i think it was possily the number of files in one directory ..... zip&tgz + asc + md5 for binary, spec and impl gives 18 files
        <jboynes>       :) that's why m2 repos have a directory heirarchy
        <kgoodson>      when i combined the source distros for RC1a it certainly looked clearer
        <kgoodson>      ok, so if you feel stronly that we should have two source distros, i can do that, and i will explain to the user list why we have not picked up on the suggestion of having one source distro -- then that makes moving samples a useful task
        <jboynes>       well, jboynes does not a straw poll make either ;)
        <jboynes>       I come from JCP land where there is a strong isolation between spec and impl
        <jboynes>       so that would shape my perspective on things
        <jboynes>       but SDO does not have the same history
        <jboynes>       e.g. it used to be you /had/ to ship spec api and impl in the same jar
        <kgoodson>      ok, help me, I believe in spec & impl separation too, but I can see that sdo/spec and sdo/impl separates the two
        <jboynes>       ok
        <jboynes>       my Q is on what you want to tag
        <jboynes>       tag == release content
        <jboynes>       i thought we were thinking of moving samples/sdo to sdo/samples so that we can tag just by copying the sdo parent directory
        <kgoodson>      i had imaged that we work on the branch until we are happy and then tag the branch, but in the branch hierarchy i have replicated the structure of the overall project, e.g. spec/sdo samples/sdo
        <jboynes>       which would tag imp, plugins, tools and samples all at the same time
        |<--    isilval_ has left irc.freenode.net ("Trillian (http://www.ceruleanstudios.com")
        <kgoodson>      that would be a step in the right direction, to be hones i'm easy, and I don't know what the right thing to do is, if there is a right thing to do
        <jboynes>       I'm not sure what you mean by "right thing to do"
        <kgoodson>      best practice, i guess
        <jboynes>       there are things you can do to make things easier
        <kgoodson>      i have not been involved in projects that do source distros before
        <jboynes>       ok
        <cr22rc>        rfeng been around any?
        <kgoodson>      haven't seen him
        <kgoodson>      jboynes, you said "there are things you can do to make things easier" -- what did you mean, can you elaborate?
        <jboynes>       so "best practice" is that a release is a "known good" version of the development tree
        <jboynes>       "known good" = stable, rebuildable, less buggy, whatever criteria you apply
        <kgoodson>      sure, i think we have that
        <jboynes>       yeah
        <jboynes>       except we don't really have a build that does just SDO
        <jboynes>       it's a mix & match thing
        <jboynes>       so the "rebuildable" it is not quite there
        <kgoodson>      so if we get to the state that we have a build for SDO spec and one for SDO impl (incl samples) then thats ideal
        <jboynes>       ok
        <jboynes>       I believe the spec build is standalone
        <kgoodson>      good, then lets do that
        <jboynes>       and also the sdo impl (sans samples)
        <jboynes>       so we can get to that by moving the samples under sdo impl
        <kgoodson>      ok, you've convinced me
        <jboynes>       under sdo, not under sdo/impl :)
        <jboynes>       I think we'd also move dist/sdo to sdo/dist
        <kgoodson>      indeed, i was using impl in a slightly loose way, that meant impl + tools + plugins -- i.e. all our implementation related stuff
        <kgoodson>      yes that would be very good
        <jboynes>       me too (just thought I wasn't being clear)
        <kgoodson>      but theres still the issue of the STATUS file
        <jboynes>       :)
        <jboynes>       yeah
        <kgoodson>      i wonder if we had a subproject for that kind of stuff that each other sub project depenmded on
        <kgoodson>      could that work?
        <kgoodson>      is that overkill?
        <jboynes>       it's more the convention of how to lay out a ASF project
        <jboynes>       project being all of tuscany
        <jboynes>       and many projects don't include their STATUS file
        <jboynes>       I happen to think that incubator projects should
        <kgoodson>      its in the draft guidelines IIRC
        <jboynes>       as i think community status is an important aspect of incubating projects
        <kgoodson>      hmm, so if we cant do some kind of symbolic link trickery then I think we are into manual copying, and all the maintenance issues associated
        <jboynes>       well, we know symlinks don't work on windows
        <jboynes>       how about if we have a manual step to copy the status file when we tag
        <jboynes>       actually, we would /need/ to do that
        <jboynes>       yeah
        <jboynes>       so, we make whoever cuts the tag responsible for copying the STATUS file from the root into the tag
        <kgoodson>      in the absence of any advanced techinal trick for sharing that fle then i think that's our only option
        <kgoodson>      ok
        <jboynes>       ok
        <kgoodson>      so we should have a release policy in place i think, so this could be a material part of that
        <jboynes>       yes
        <jboynes>       +1
        <kgoodson>      i had started collecting info on the wiki
        <kgoodson>      so i will make sure this is at least recorded there, and then plan to sanitize it later
        <jboynes>       as an aside, I like what robert did on the proposal guidelines for the incubator
        <jboynes>       guideline + reasoning + examples
        <kgoodson>      i have looked at lots of docs recently, so i'm not sure exactyly which doc you are talking about
        <kgoodson>      is that the http://*****/releasemanagement link
        <kgoodson>      ?
        <jboynes>       http://incubator.apache.org/guides/proposal.html
        <jboynes>       (sorry, went looking)
        <jboynes>       in the templatebit
        <kgoodson>      ok, i'll take a look, so did you mention that as a suggestion for the format of the release policy?
        <kgoodson>      yes, on first scan that looks like a useful doc
        <jboynes>       yes
        <jboynes>       I think "why" is important :)
        <kgoodson>      "yes" to usefulness, or proposal for format? on the "why" issue, I couldn't agree more
        <jboynes>       I liked the way in this document robert was able to mix guideline with "why" with an example of "how"
        <jboynes>       a reference on style (not content)
        <kgoodson>      right, i'll put the proposal element on the wiki, with a link to this doc as a style suggestion
        <jboynes>       thanks
        <jboynes>       where were we? :)
        <jboynes>       ok, tag by copying "sdo"
        <jboynes>       includes impl etc. and samples
        <jboynes>       and then copy in STATUS
        <kgoodson>      yes
        <jboynes>       tag spec/sdo in the same way
        <jboynes>       also the parent pom and the buildtools
        <kgoodson>      so i'll need to rearrange my branch to match the trunk
        <jboynes>       rm & recopy?
        <kgoodson>      as to the parent pom, i was planning to digest a fair chunk of the free maven book this weekend and become a power maven user, but alas that didnt work out
        <jboynes>       :)
        <jboynes>       anything I can help with (as I set that up) ?
        <kgoodson>      theres been no change in the samples trunk so i can rm and recopy, yes
        <jboynes>       I was thinking the whole thing
        <jboynes>       would be easy (but assumes nothing really changed in trunk(
        <kgoodson>      well, i can't recall exactly what my issue was wehn i had to stop on friday night, but my branch was not building correctly, because of something to do with the parent pom
        <jboynes>       ok
        <kgoodson>      in the branch, after having copied in the samples stuff and tried to build from distributuion/sdo i was getting ...
        <kgoodson>      [INFO] ---------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ---------------------------------------------------------------------
[INFO] Error building POM (may not be this project's POM).


Project ID: org.apache.tuscany.samples.sdo:sample-sdo:jar:1.0-incubator-M2-S

Reason: Cannot find parent: org.apache.tuscany.samples:parent for project: o
incubator-M2-SNAPSHOT


[INFO] ---------------------------------------------------------------------
[INFO] For more information, run Maven with the -e switch
[INFO] ---------------------------------------------------------------------
[INFO] Total time: 26 seconds
[INFO] Finished at: Fri Sep 29 17:29:43 BST 2006
[INFO] Final Memory: 8M/23M
[INFO] ---------------------------------------------------------------------

C:\Development\Tortoise\distroTest3\branches\sdo-java-M2\distribution\sdo>
        <kgoodson>      so i figured i had to go play with the parent pom
        <jboynes>       I can see that
        <jboynes>       I think it will go away if we move samples under sdo
        <jboynes>       currently the parent for samples/sdo is the pom in samples
        <jboynes>       so that would need to be released or tagged as wel
        <jboynes>       if we move the samples, then the parent would be the pom in "sdo"
        <kgoodson>      ok, sounds good, i wan't planning on attacking that for a few hours as i have domestic duties here before bedtime --- can this wait until the morning, or is it something you could readily do?
        <kgoodson>      don't get me wrong, i'm happy to do this stuff, but I'm feeling a little rough round the edges at the moment
        <jboynes>       i can do, can you drop a note to the list so everyone knows what's going on ?
        <kgoodson>      will do
        <jboynes>       I have 8 hours on you :)
        <kgoodson>      :-)
        <jboynes>       and haven't started drinking yet
        <jboynes>       (it's football day - 49ers just lost 41-0)
        <kgoodson>      ah, its been a rugby day here, both offspring won their matches, but torrential rain didn't make it the best of days for spectating :-(
        <jboynes>       :)
        <jboynes>       up for one more question?
        <kgoodson>      sure
        <jboynes>       in the binary distro, what do you want the samples to look like?
        <kgoodson>      hmmm, good point
        <kgoodson>      i guess its usual to copy the source of the samples into a binary distro
        <kgoodson>      i cant recall exactly waht it looks like at the mo, i could take a look
        <jboynes>       ok
        <jboynes>       ok, I'll just move what's there around
        <jboynes>       thanks
        <kgoodson>      thank you
        =-=     YOU are now known as kgoodson_away
        [INFO]  You are now marked as away (User is away.). Click the nickname button or use the |/back| command to return from being away.

== getting the samples souce code in the binary distribution ===

added

    <build>
        <sourceDirectory>src/main/java</sourceDirectory>
            <resources>
                <resource>
                    <directory>src/main/java</directory>
                </resource>
            <resource>
                <directory>src/main/resources</directory>
            </resource>
        </resources>
     <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <configuration>
          <archive>
            <manifest>
              <mainClass>org.apache.tuscany.samples.sdo.ExecuteSamples</mainClass>
            </manifest>
          </archive>
        </configuration>
      </plugin>
    </plugins>

to sample/pom.xml. The first chunk gets the source code in there, and the second chunk allows you to run "java -jar <jarfile>.jar" to run the top level sample program.

getting javadoc into the repository for the distribution build to pick up

nyone got time for a maven question? ant? lresende?
        <ant>   can try but i'm no maven expert
        <kgoodson>      thx
        <kgoodson>      i currently have 5 peer projects, impl, tools, plugin, sample and distribution
        <kgoodson>      distribution can pick up the outputs of the first 4 and package them, becasue they are in the repository
        <kgoodson>      but if i want javadoc from any of them then i'm not sure what the best way is of doing that, as currently it would require a releative file path that ascends above the pom of the distribution project
        <kgoodson>      i was going to put the incantations to create the distribution build in the pom above the impl, sample etc
        <kgoodson>      but i just thought i'd check to see if there was a clean wayof say putting the savadoc in the repository so that it could be picked up by the distribution projects pom
        <kgoodson>      s/sava/java/
        <kgoodson>      any thoughts?
        <ant>   bot sure the javadoc could go in the repository, but other no idea sorry
        <ant>   dkulp seems like a maven wizz, maybe he could suggest something
        <kgoodson>      ok, i'll plug on with raising the responsibiliity fo creating the distribution to the parent pom thanks
        <kgoodson>      ok i'll ping him
        <kgoodson>      ta
        <kgoodson>      dkulp? yy?
        <kgoodson>      yt?
        <kgoodson>      i guess "yy" means "are you you?" Which is a little deep for a Friday afternoon ;-)
        <dkulp> Semi here. I have a meeting to run to soon though.
        <kgoodson>      ok, thx, can you see my question about dmaven and javadoc above?
        <kgoodson>      s/dmaven/maven/
        <dkulp> You can run "mvn javadoc:jar install" top level
        <dkulp> Then ALL the javadocs would be put in the repository.
        <dkulp> The distributions could then package them view a "qualifier" on the dependency.
        <kgoodson>      not sure i understand last sentence
        <dkulp> I mean classifier.
        <dkulp> Preparing a paste.....
        <kgoodson>      ok, but still having trouble parsing the meaning, sorry
        <kgoodson>      you don't know off-hand where an example might be do you?
        <dkulp> http://rafb.net/paste/results/omhydW43.html
        <kgoodson>      ta
        <dkulp> That's a snipit from the CXF distribution pom.xml
        <kgoodson>      many thanks
        <dkulp> It unpacks the javadoc from the repository into target/javadoc for the assembly to grab.
        <kgoodson>      heh heh, thx, i'll play
        <dkulp> Maven dependencies have a options "classifier" (defaults to "jar") to specify the type of dependency.
        <kgoodson>      i see, so here we override with javadoc
        <dkulp> There are other types like "test" (you can run "mvn test:jar install" to get test jars), javadoc, etc...
        <dkulp> Right
        <dkulp> Hope that helps.
        <kgoodson>      i think i can see the steps forward to do this, many thanks
        <dkulp> No problem. :-)

and here's the pastbin referred to above

            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>dependency-maven-plugin</artifactId>
                <version>${dependency.plugin.version}</version>
                <executions>
                    <execution>
                        <id>unpack-javadoc</id>
                        <phase>package</phase>
                        <goals>
                            <goal>unpack</goal>
                        </goals>
                        <configuration>
                            <outputDirectory>${project.build.directory}/javadoc</outputDirectory>
                            <artifactItems>
                                <artifactItem>
                                    <groupId>${pom.groupId}</groupId>
                                    <artifactId>cxf-api</artifactId>
                                    <classifier>javadoc</classifier>
                                    <version>${pom.version}</version>
                                </artifactItem>
                            </artifactItems>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

The incantation in a pom with equivalent effect to dkulps mvn javadoc:jar install seemed to be ...

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <configuration>
                    <overview>${basedir}/src/main/java/commonj/sdo/overview.html</overview> 
                    <version>2.0</version>
                </configuration>
                <executions>
                    <execution>
                        <id>package</id>
                        <phase>package</phase>
                        <goals>
                            <goal>jar</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

It required the phase to be package rather than install before it would put the javadoc-jar into the repository (the command line version did this fine)

points to include

  1. take a zip of your maven repository when you create a release -- especially when there are any snapshot plugins you are using. You can't be sure that you will be able to build your release in the same way (or at all) if one of the plugins later instroduces an issue!

I discovered this by looking at http://svn.apache.org/viewvc/incubator/cxf/trunk/api/pom.xml?view=markup

==========================

   svn copy https://svn.apache.org/repos/asf/incubator/tuscany/java/spec/sdo-api https://svn.apache.org/repos/asf/incubator/tuscany/branches/java/suitable-branch-name/sdo-api
   svn copy https://svn.apache.org/repos/asf/incubator/tuscany/java/sdo https://svn.apache.org/repos/asf/incubator/tuscany/branches/java/suitable-branch-name/sdo

Tuscany/TuscanyJava/SDOJavaReleaseSteps/RoughNotes (last edited 2009-09-20 22:48:21 by localhost)