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

[Scott Marlow]

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