activemq-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Clebert Suconic <clebert.suco...@gmail.com>
Subject Re: How to rebuild the docs for Artemis?
Date Mon, 14 Nov 2016 17:15:35 GMT
maintaining the website is pretty much a committers responsability.
it's done through SVN. There's a link somewhere in apache.org
explaining how to do it.

Too many changes would be something that makes the documentation too
far from the released version. Just common sense... we can exercise
our judgment here and adapt the workflow when needed. that was my
point.

I don't think we need to be strict on this case. it was a simple
change that could have been updated on the website. Was just saying we
don't really need to change the workflow now.. but I don't see an
issue on changing it at any point.

On Mon, Nov 14, 2016 at 11:55 AM, Antoine Toulme
<antoine.toulme@gmail.com> wrote:
> Is anybody besides you aware of how to edit and push docs on the website?
>
> What is too many changes?
>
>> On Nov 14, 2016, at 8:22 AM, Clebert Suconic <clebert.suconic@gmail.com> wrote:
>>
>> 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
>



-- 
Clebert Suconic

Mime
View raw message