activemq-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Justin Bertram <jbert...@apache.com>
Subject Re: How to rebuild the docs for Artemis?
Date Mon, 14 Nov 2016 21:01:00 GMT
I think if Artemis moved to a more rapid release cycle this wouldn't be much of an issue.

Also, people who updated the documentation could either:

  -ensure their changes were part of the -Prelease build before they sent a PR

or

  -check the documentation for the expected updates when the release was up for a vote

I don't see a reason to make a big change to the documentation scheme.


Justin

----- Original Message -----
From: "Clebert Suconic" <clebert.suconic@gmail.com>
To: dev@activemq.apache.org
Sent: Monday, November 14, 2016 1:34:14 PM
Subject: Re: How to rebuild the docs for Artemis?

It is maintained at this SVN:

https://svn.apache.org/repos/infra/websites/production/activemq/content/artemis

you just need your apache credentials.



> I don't think its a good idea for us to focus on just this change.


maybe I'm getting lost in translation and not finding the right
words... I was just trying to say.. whenever we need it to be more
dynamic, we can just change the website and do it. I consider myself a
doer :).. no reason to debate over this IMHO.


Notice that github also presents you a live copy of the docs, we can
always point a link somewhere:

https://github.com/apache/activemq-artemis/blob/master/docs/user-manual/en/SUMMARY.md


On Mon, Nov 14, 2016 at 2:25 PM, John D. Ament <johndament@apache.org> wrote:
> On Mon, Nov 14, 2016 at 12:15 PM Clebert Suconic <clebert.suconic@gmail.com>
> wrote:
>
>> 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.
>>
>
> Except, as a committer, I have no idea how to do it.  I checked some of the
> typical spots and couldn't find 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.
>>
>
> I don't think its a good idea for us to focus on just this change.
>
>
>>
>> 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
>>



-- 
Clebert Suconic

Mime
View raw message