Mailing-List: contact dev-help@activemq.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@activemq.apache.org
MIME-Version: 1.0
In-Reply-To: <4CA1BD12-601D-46C7-9F11-F58E726DC012@gmail.com>
References: <CAOqetn89onw7wghmoV2YES6BMsN6BXrM-R4VyEXLOqxEvWGWag@mail.gmail.com>
 <1384148928.13193786.1478894252420.JavaMail.zimbra@redhat.com>
 <CAOqetn8DoyGT33Jtzr80TxmaTBLpQ0rmEk=a_eo6VVKMX0YVLw@mail.gmail.com>
 <CAKF+bsp8rPsG3oRxaAOw_NMpyFmQPzpi=zSaynwkq8JVEC7n8Q@mail.gmail.com>
 <CAOqetn9KOa681WKAfCpZ3fGLnGSRmt0BoYHjW=gH9ya1CtMrOg@mail.gmail.com>
 <CAH6wpnpKJOtd-1Hcz5oHZxzeScw0iSGJiMydnjZmFK4-6GC4iQ@mail.gmail.com> <4CA1BD12-601D-46C7-9F11-F58E726DC012@gmail.com>
From: Clebert Suconic <clebert.suconic@gmail.com>
Date: Mon, 14 Nov 2016 11:22:03 -0500
Message-ID: <CAKF+bsogUShV6_eHmCf0khWd4w=1VOWFZ7RKfsj7Bhf6a9wUSQ@mail.gmail.com>
Subject: Re: How to rebuild the docs for Artemis?
To: "dev@activemq.apache.org" <dev@activemq.apache.org>
Content-Type: text/plain; charset=UTF-8
archived-at: Mon, 14 Nov 2016 16:22:14 -0000

The docs on the webiste are not necessarily part of the release.. they
just document how to use a current release. Some options are not
available in 1.4, only on 1.5... etc...

Now, we can't change the release for sure since it's signed and voted.

I think it's ok to make a small change to the 1.5.0 release and push
it directly to the webiste...  I prefer doing it as part of the
release.. but we can treat small exceptions occasionally.


What about this: If we start making too many changes to the docs (like
if someone is reviewing docs.. etc.. we can then upload a snapshot of
the docs to the website). Right now it's not really needed.. but if we
need it we can change the workflow at any point (when needed). WDYT?


On Mon, Nov 14, 2016 at 11:18 AM, Antoine Toulme
<antoine.toulme@gmail.com> wrote:
> At Apache Buildr we push the docs out to the website without mapping them to a release.
>
> We also push changes on a release.
>
> We never update released bits - they're signed and voted and all.
>
>> On Nov 14, 2016, at 08:11, Martyn Taylor <mtaylor@redhat.com> wrote:
>>
>> I'm not 100% I am following properly here, but a couple of points:
>>
>> The documentation API/user manual is currently shipped with the release.
>> So there's no way to update this after the release is out.  We do host
>> copies of the documentation (and some additional formats) here:
>>
>> https://activemq.apache.org/artemis/docs.html
>>
>> These could be updated after a release.  But would mean there's a
>> differences between what we ship and what we host online.  If we want to
>> separate the documentation and the release, then perhaps we remove the docs
>> from the release altogether, and point users our docs page, which we can
>> update periodically?
>>
>> John, regarding your comments about pushing to docs periodically, could you
>> please explain how this works? could you point to me to a project that does
>> this so I can take a look?
>>
>> Thanks
>> Martyn
>>
>>
>>
>>
>>
>> On Mon, Nov 14, 2016 at 3:46 PM, John D. Ament <johndament@apache.org>
>> wrote:
>>
>>> On Mon, Nov 14, 2016 at 10:29 AM Clebert Suconic <
>>> clebert.suconic@gmail.com>
>>> wrote:
>>>
>>>>> I'm against the idea of storing the docs outside the source repository.
>>>> It
>>>>> just makes sense for them to live together.  When you're looking at a
>>>>> release bundle, the docs within it should match the release you pulled
>>>> down.
>>>>>
>>>>> I don't have an issue with us hosting multiple releases worth of docs,
>>>> even
>>>>> though at apache we only ever consider the latest release as valid.  I
>>>>> think it would be beneficial for us to have docs setup for the current
>>>>> snapshot as well.  This way we can see if users have feedback on the
>>>>> current goings on.  That's where I'm talking about the continuous
>>> aspect
>>>> of
>>>>> this.  They could even go into a SNAPSHOT folder.
>>>>>
>>>>
>>>> That would encourage snapshot usage IMO.
>>>>
>>>
>>> I don't understand this point.  The ASF acknowledges snapshots.  There's
>>> nothing wrong with snapshots, as long as its clear that:
>>>
>>> - Its not an official release
>>> - Taking the "official release" isn't a process involving cloning the
>>> current master/head of the repo.
>>>
>>> Do you have concerns with using snapshots?  I think its actually a good
>>> practice, to make sure there's no compatibility issues for users or
>>> ourselves.
>>>
>>>
>>>> As of now I will just update 1.5.0 HTML with the change you made.
>>>>
>>>


-- 
Clebert Suconic