[hibernate-dev] Minor issues/questions about Hibernate Core/ORM documentation

Fri Jan 13 07:58:39 EST 2012

Interesting.  I was trying `git log --grep=HHH-6906` but getting nothing 
back.

`git reflog | grep HHH-6906` returns:
39d47c4 HEAD@{89}: commit: HHH-6906 - Clean up javadoc warnings

I only use my fork for "on going" work, especially if it has to be 
collaborated.  I never used my fork for this work.

Hardy, the showed that link because it shows the release.gradle file in 
its most advanced state.  The aggregateJavadoc task on master HEAD right 
now is its initial form from WAY back.  Lots of the edits to that file 
are gone now:

6029c45 HEAD@{90}: commit: HHH-6782 - define javadoc groups based on 
api/spi/internal

On 01/12/2012 10:23 PM, Scott Marlow wrote:
> I took a quick look at and didn't see a likely branch. You might look in
> the output from "git reflog" (in your local personal Hibernate fork
> folder) for "HHH-6906 - Clean up javadoc warnings". I think that will
> contain the changes, even if your fork no longer has the branch that
> referenced it.
>
> The "git reflog" output will look something like:
>
> d0ce6e6 HEAD@{0}: rebase -i (finish): returning to refs/heads/cluster9
> d0ce6e6 HEAD@{1}: rebase -i (pick): AS7-3229 add
> defaultReadObject/WriteObject calls
> 10c2786 HEAD@{2}: rebase -i (pick): AS7-3279 upgrade to Hibernate
> 4.0.1.Final
> ea02cae HEAD@{3}: rebase -i (pick): trace logging for xpc serialization
> 1fb5d2a HEAD@{4}: rebase -i (squash): xpc serialization test case
> 5bc81e8 HEAD@{5}: rebase -i (squash): updating HEAD
> 07c215a HEAD@{6}: checkout: moving from cluster9 to 07c215a
> aab8f78 HEAD@{7}: checkout: moving from AS7-3279 to cluster9
>
> Lets say that someone, my HEAD@{2} change was lost from master. I could
> "git merge 10c2786" to pull it back into my fork and then cherry pick it
> from master. I haven't actually tried this myself, I just read about it.
> Hope this helps.
>
> Scott
>
> On 01/12/2012 11:03 PM, Scott Marlow wrote:
>> Are the doc commits visible on your personal Hibernate fork still? I
>> know that "gitk" will visualize the master branch or whatever branch.
>> Maybe you can see the doc commits on the master and a merge that took
>> them out (or not ;).
>>
>> We should be able to "git cherry-pick commit-id" the commits from your
>> fork, back to master (if they are still on your branch).
>>
>> On 01/12/2012 09:58 PM, Steve Ebersole wrote:
>>> Can anyone with better git-fu than me tell me where those changes went?
>>>
>>>
>>> On Thu 12 Jan 2012 08:44:19 PM CST, Steve Ebersole wrote:
>>>> Actually wrt aggregateJavadocs, some how all those edits to
>>>> release.gradle are gone on master :(
>>>>
>>>>
>>>> On Thu 12 Jan 2012 03:48:46 PM CST, Steve Ebersole wrote:
>>>>>
>>>>> On Thu 12 Jan 2012 03:19:29 AM CST, Hardy Ferentschik wrote:
>>>>>> Answers inline
>>>>>>
>>>>>> On Jan 12, 2012, at 9:50 AM, Gail Badner wrote:
>>>>>>
>>>>>>> I've uploaded the 4.0.1.Final documentatation to
>>>>>>> http://docs.jboss.org/hibernate/core/4.0/.
>>>>>>>
>>>>>>> Maybe this was already discussed but, should the switch from "core"
>>>>>>> to "orm" affect the URL for the 4.0 documentation (i.e.,
>>>>>>> http://docs.jboss.org/hibernate/orm/4.0/)?
>>>>>>
>>>>>> I think it makes sense to switch the urls. However, in this case I
>>>>>> suggest we also put a redirect in place for
>>>>>> http://docs.jboss.org/hibernate/core/4.0/ to
>>>>>> http://docs.jboss.org/hibernate/orm/4.0/
>>>>>> Just renaming the directories is probably not a good idea due to
>>>>>> bookmarks and people used to go to the 'core' url. If we change to
>>>>>> orm we need to update the pointers from
>>>>>> http://www.hibernate.org/docs
>>>>>
>>>>> I agree, we should do a redirect. I had not planned on changing the
>>>>> physical dir until 4.1 as that is when the new docs would be getting
>>>>> used. 6 in one... if you feel the itch, go for it.
>>>>>
>>>>>
>>>>>>> Also, I noticed that http://docs.jboss.org/hibernate/stable/core/
>>>>>>> points to 3.6.9.Final docs. Should it point to
>>>>>>> http://docs.jboss.org/hibernate/core/4.0/ (or
>>>>>>> http://docs.jboss.org/hibernate/orm/4.0/)?
>>>>>>
>>>>>> Stable should definitely point to 4.0. That's independent of whether
>>>>>> we rename the urls
>>>>> + 1
>>>>>
>>>>>
>>>>>>> I ended up using the documentation downloaded from the SourceForge
>>>>>>> distribution because I got errors when I tried to build the Javadoc
>>>>>>> from the 4.0.1 tag using "gradle javadoc":
>>>>>>>
>>>>>>> /NotBackedUp/gbadner/git/hibernate-core-master/hibernate-core/src/main/java/org/hibernate/metamodel/source/annotations/HibernateDotNames.java:109:
>>>>>>>
>>>>>>> cannot find symbol
>>>>>>> symbol : variable DotName
>>>>>>> location: interface
>>>>>>> org.hibernate.metamodel.source.annotations.HibernateDotNames
>>>>>>> DotName ACCESS_TYPE = DotName.createSimple(
>>>>>>> AccessType.class.getName() );
>>>>>>>
>>>>>>> What command should be used to build Javadoc?
>>>>>>
>>>>>> 'gradle javadoc' is the default javadoc task which you get when you
>>>>>> use the Java plugin. It build the javadocs for the current module.
>>>>>> In our case we don't use this task, because
>>>>>> we want aggregated docs. To get the aggregated docs you need to run
>>>>>> the 'aggregateJavadocs' from the release module.
>>>>>>
>>>>>> './gradlew aggregateJavadocs'
>>>>>
>>>>> Just a minor point. If you run it from the release module, it has to
>>>>> be `../gradlew aggregateJavadocs`
>>>>>
>>>>> Alternatively from root you could run `./gradlew
>>>>> :release:aggregateJavadocs`
>>>>>
>>>>>
>>>>>> FYI, the javadoc task needs all dependencies on the classpath when
>>>>>> executing. Looking at the error it seems jandex is not on the
>>>>>> classpath. This might be related to HHH-6921, but that's just a
>>>>>> guess.
>>>>>> As said, the default javadocs tasks are not configured, because we
>>>>>> are only interested in the aggregated docs.
>>>>>
>>>>> I think Strong only changed that to move jandex to the provided
>>>>> configuration. I was able to run these fine when I did the build.
>>>>>
>>>>>
>>>>>>> I also noticed that the Javadoc includes test classes. It would be
>>>>>>> nice to exclude those.
>>>>>>
>>>>>> right, even the aggregated docs seem to include test classes. I
>>>>>> would create a jira and we reconfigure the task for the next release
>>>>>
>>>>> Hmm, I spent a lot of time getting those right.
>>>>> https://fisheye2.atlassian.com/changelog/Hibernate-Core?cs=39d47c4b39f231435305b47e23f4b2cf8e9aede8#releaseZ002frelease.gradle
>>>>>
>>>>>
>>>>>
>>>>> If they are back, something after fucked those changes up.
>>>>>
>>>>>
>>>>>>> I really liked how convenient it was to be able to just copy the
>>>>>>> contents of the documentation directory from the distribution into
>>>>>>> the staging directory for rsync-ing. The only change I had to make
>>>>>>> after copying was to change hem/en to hem/en-US. I haven't looked
>>>>>>> into this, but I imagine that would be an easy thing to fix.
>>>>>
>>>>> We should update that in the source tree. But to be honest, hem docs
>>>>> should really just go away as a separate thing. Their content should
>>>>> be merged into the main docs.
>>>>>
>>>>>
>>>>>>
>>>>>>
>>>>>> _______________________________________________
>>>>>> hibernate-dev mailing list
>>>>>> hibernate-dev at lists.jboss.org
>>>>>> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>>>>
>>>
>>
>> _______________________________________________
>> hibernate-dev mailing list
>> hibernate-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>

-- 
steve at hibernate.org
http://hibernate.org