aries-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Jencks <david.a.jen...@gmail.com>
Subject Re: The project website
Date Sat, 22 Aug 2020 23:05:10 GMT
Progress:

- CMS content history and initial antora migration is in the aries-antora-site repo
- Published site history is in aries-site-pub repo
- html pages from CMS and those in the published site (except for duplicates) are now visible
in Antora site. They don’t all look great, but they are there.
- javadoc pages are also in the site and accessible
- I think the nav has all the pages except javadoc
- I constructed an .htaccess file which redirects from all locations from the old site to
the new site, including the xsd urls.  This does not include the apparent mistakes of duplicate
files.
- The not-found pages for .htaccess are listed in the aries-antora project in dot-htaccess-not-found
- I added a package.json and playbook for building the content that happens to be in the aries-antora-site
repo locally.  This will be one of many, don’t think it can be used for building the site.
- I started on a script to publish to aries-site-pub repo.

Next steps:

- I don’t think we want commits to aries-site-pub to go to the commits list, having source
updates from aries-antora-site will be more than enough.  Infra requires commit emails go
somewhere, and they  suggested setting up a list just for this.  I think this is a fine idea,
how about aries-site-pub for the list name?

- when this issue of where the emails go is resolved I’ll work more on the publish script;
I’m hoping it will be straightforward to get the script working locally, figure out an asf.yml
to publish to a preview site.  At this point I’ll point out the preview.

- next, figure out how to run the script on ASF hardware.  I think there’s a requirement
that only PMC members can cause the site to be published, so I don’t think it can work off
a commit trigger.

- at some point I’ll write some instructions in README.adoc files.

Comments:

- I think we can take advantage of Antora’s multi-version capabilities by tagging something
like the current state (in aries-antora-site) as “legacy” and keeping that as a version.
 On master we can delete obsolete content, but it will still be visible in the legacy version.
 We could mark content to be deleted with a header attribute ‘obsolete’ and generate a
list of these pages while we consider.  (cf. auto-index.adoc).

- I think the utility of the per-source-repo ‘author-mode’ builds is a stronger argument
for keeping the ui in a separate repo than my strong personal preference to do so.  We’re
shortly going to have (subproject-count) + 2 repos with playbooks in them, and any argument
for putting the UI in one is just about as strong as for another…… very weak IMO.  I suggest
you try out the current arrangement before rejecting it.  It will get easier when I write
some docs.

The next steps are, I think, going to involve pushing the new build site to aries-site-pub,
so we need to either agree that commit emails going to commits@aries.apache.org are fine or
agree to set up another list.

David Jencks

> On Aug 21, 2020, at 11:18 PM, Romain Manni-Bucau <rmannibucau@gmail.com> wrote:
> 
> Still think playbook and ui module must be merged.
> Both will never be released anyway and it makes things easier.
> 
> Site history should just be a folder imo, not a repo...
> 
> 
> Le sam. 22 août 2020 à 02:11, David Jencks <david.a.jencks@gmail.com> a
> écrit :
> 
>> A couple more comments on playbooks…
>> 
>> Since IIUC we’re planning to add docs for all the more recent subprojects
>> that each live in their own repo, to those repos, the “production” playbook
>> can’t prefer one over the others and be in a content repo.
>> 
>> However, we can easily provide a “preview” playbook in each repo for
>> building just the content in that repo, to check local  changes in more
>> detail than in the IntelliJIDEA asciidoctor plugin.
>> 
>> David Jencks
>> 
>>> On Aug 21, 2020, at 3:18 PM, David Jencks <david.a.jencks@gmail.com>
>> wrote:
>>> 
>>> Here are the repos and why they should be separate:
>>> 
>>> aries-antora-site.  This contains the content migrated from CMS.  It
>> might be possible to migrate all of these into the repos that have the
>> related source code, but I don’t think that’s really appropriate for stuff
>> about the community, board reports, etc.  In any case that’s a step for
>> after the new web site is working.  Generally this is what you’d modify
>> when working on documentation improvements.
>>> 
>>> aries-antora. This contains the playbook.  Antora works without a
>> checked out copy of the source .adocs, but the playbook does need to be
>> checked out.  Therefore this needs to be a separate project.  It’s possible
>> to put this in with the sources, but it’s a bad idea IMO.  Generally this
>> is going to be modified only when a new subproject is added to the
>> documentation, or, if we decide on versioned documentation for some
>> components, possibly when a new version is published (although most likely
>> this can be handled by wildcards).
>>> 
>>> aries-antora-ui.  The content here is almost all MPL2.0 licensed.  I
>> checked on legal discuss, and the consensus was that it was fine to have
>> such content in an Apache repo as long as it never becomes part of a
>> release.  In order to make the licensing more obvious, I think it’s
>> imperative to keep this in a separate repo that we can prominently label
>> “don’t release anything from this repo”.  I think few people are going to
>> work on this, and as it will change infrequently we’d save some build time
>> and automation complexity by keeping it separate.
>>> 
>>> aries-site-pub.  This currently contains the CMS site history, and is
>> going to be where the new build process commits the site to publish it.  No
>> one should be modifying it by hand.
>>> 
>>> David Jencks
>>> 
>>>> On Aug 21, 2020, at 6:07 AM, Raymond Auge <raymond.auge@liferay.com.INVALID>
>> wrote:
>>>> 
>>>> Personally, I would really appreciate only having to work with the main
>>>> source repo and at most with the sub project repos. Having the site
>> tech in
>>>> multiple repos serves only to annoy me (and I feel anyone) that wants to
>>>> provide quick fixes or just ramp up on updating docs due to a higher
>>>> barrier for testing.
>>>> 
>>>> That's my opinion at least. I had assumed the multiple repos you used
>> David
>>>> were merely for testing (I also do understand the publish repo that
>> holds
>>>> the built site...)
>>>> 
>>>> - Ray
>>>> 
>>>> On Fri, Aug 21, 2020 at 3:05 AM Romain Manni-Bucau <
>> rmannibucau@gmail.com>
>>>> wrote:
>>>> 
>>>>> Le ven. 21 août 2020 à 08:36, David Jencks <david.a.jencks@gmail.com>
>> a
>>>>> écrit :
>>>>> 
>>>>>> 
>>>>>> 
>>>>>>> On Aug 20, 2020, at 11:17 PM, Romain Manni-Bucau <
>>>>> rmannibucau@gmail.com>
>>>>>> wrote:
>>>>>>> 
>>>>>>> Le ven. 21 août 2020 à 08:15, David Jencks <david.a.jencks@gmail.com
>>>>>> <mailto:david.a.jencks@gmail.com>> a
>>>>>>> écrit :
>>>>>>> 
>>>>>>>> 
>>>>>>>> 
>>>>>>>>> On Aug 17, 2020, at 10:43 PM, Romain Manni-Bucau <
>>>>>> rmannibucau@gmail.com>
>>>>>>>> wrote:
>>>>>>>>> 
>>>>>>>>> Le mar. 18 août 2020 à 02:24, David Jencks <
>> david.a.jencks@gmail.com
>>>>>> 
>>>>>> a
>>>>>>>>> écrit :
>>>>>>>>> 
>>>>>>>>>> I’ve created 4 repos at Apache for this and started
to move the
>>>>>> content
>>>>>>>> to
>>>>>>>>>> them.
>>>>>>>>>> 
>>>>>>>>> 
>>>>>>>>> Why 4? Dont we only need the build and publish ones if
we put docs
>> in
>>>>>>>> each
>>>>>>>>> code repo? Theme should probably stay with build one
to avoid to
>> make
>>>>>> it
>>>>>>>>> complex since we couple them anyway.
>>>>>>>> 
>>>>>>>> Well, I’ve had 3 all along, and the 4th is to publish to.
 I much
>>>>> prefer
>>>>>>>> keeping all the separate aspects in separate repos.
>>>>>>>> At the moment I’m waiting on infra for
>>>>>>>> https://issues.apache.org/jira/browse/INFRA-20724 <
>>>>>>>> https://issues.apache.org/jira/browse/INFRA-20724 <
>>>>>> https://issues.apache.org/jira/browse/INFRA-20724>>.
>>>>>>>> 
>>>>>>> 
>>>>>>> Any reason? It just adds complexity and slows down the build
>> (multiple
>>>>>> hits)
>>>>>> 
>>>>>> If you’re building locally, the UI is downloaded when you run npm
i
>> (or
>>>>>> preferably nom run clean-install).  If they are in one repo, you
have
>> to
>>>>>> build the UI every time to be sure it’s up to date.  If it’s
>> referenced
>>>>> in
>>>>>> an already built state, that’s much faster.
>>>>>> 
>>>>> 
>>>>> Not really, generally all frontend projects push the build state so you
>>>>> just reference the built state and when you change it, rebuild it
>> locally
>>>>> and update the pushed state so this is not an issue IMHO.
>>>>> Issue is keep synchronizing repos for nothing or having to clone N
>> repo to
>>>>> work on the website locally. Any indirection increases the entry cost
>> ;).
>>>>> 
>>>>> 
>>>>>> 
>>>>>> However, I find that keeping the UI, playbook, and sources in
>> different
>>>>>> repo helps keep my thinking more organized, which is far more
>> important
>>>>> to
>>>>>> me than slight time savings.
>>>>>> 
>>>>> 
>>>>> Source and build repo yes, but UI and playbook don't need to be split
>> at
>>>>> all and from experience, when it is not reusable - our case - it is
>> saner
>>>>> to keep them in the same repo so I think we should merge it.
>>>>> 
>>>>> 
>>>>>> 
>>>>>> David Jencks
>>>>>>> 
>>>>>>>> 
>>>>>>>>> 
>>>>>>>>>> One repo, aries-site-pub, is for publishing the built
site from.
>>>>>>>> Locally
>>>>>>>>>> I used svn2git to get the whole history of the published
site out
>> of
>>>>>>>> svn.
>>>>>>>>>> Infra doesn’t seem to recommend doing this, but
I think it will be
>>>>>>>>>> extremely handy to be able to see the history in
one place without
>>>>>>>> having
>>>>>>>>>> to deal with svn.
>>>>>>>>>> 
>>>>>>>>>> I’ve already realized that
>>>>>>>>>> 
>>>>>>>>>> - there are a bunch of schemas to serve.  These can
go in an
>>>>>> attachments
>>>>>>>>>> directory.
>>>>>>>>>> 
>>>>>>>>> 
>>>>>>>>> We have some per project so likely a folder per module
or just
>>>>> specific
>>>>>>>>> links outside antora since we should never delete one,
no?
>>>>>>>> 
>>>>>>>> I realized I already put them in attachments, I just didn’t
know
>> about
>>>>>> the
>>>>>>>> redirects.  If we end up docs for blueprint, jpa, etc. in
the repo
>> the
>>>>>> code
>>>>>>>> is in we can move the  schemas too and have yet more redirects.
>>>>>>>> 
>>>>>>>>> 
>>>>>>>>> - there’s an existing .htaccess file with a few redirects,
and we
>>>>> need
>>>>>>>> one
>>>>>>>>>> that also shows the new location of every previously
existing
>> page.
>>>>>>>>>> 
>>>>>>>>>> I’ll work on this…
>>>>>>>>>> 
>>>>>>>>> 
>>>>>>>> 
>>>>>>>> I’m most of the way to having a reasonable .htaccess.
>>>>>>>> 
>>>>>>>>> Sounds great, we keep httpd right?
>>>>>>>> 
>>>>>>>> I don’t think we have a choice about that :-) anyway I
have no
>>>>> problems
>>>>>>>> with it…
>>>>>>>> 
>>>>>>>>> Thans a lot David.
>>>>>>>>> 
>>>>>>>> 
>>>>>>>> Thanks
>>>>>>>> David Jencks
>>>>>>>>> 
>>>>>>>>>> David Jencks
>>>>>>>>>> 
>>>>>>>>>>> On Aug 14, 2020, at 9:54 AM, David Jencks <
>>>>> david.a.jencks@gmail.com>
>>>>>>>>>> wrote:
>>>>>>>>>>> 
>>>>>>>>>>> I updated the feather to the current svg version,
adjusted the
>>>>>> spacing
>>>>>>>> a
>>>>>>>>>> bit, and added some basic instructions to the UI
project.
>>>>>>>>>>> 
>>>>>>>>>>> David Jencks
>>>>>>>>>>> 
>>>>>>>>>>>> On Aug 13, 2020, at 12:29 AM, Romain Manni-Bucau
<
>>>>>>>> rmannibucau@gmail.com
>>>>>>>>>> <mailto:rmannibucau@gmail.com>> wrote:
>>>>>>>>>>>> 
>>>>>>>>>>>> Starts to look very good, some sizing and
the feather to change
>> to
>>>>>>>> have
>>>>>>>>>> a better quality and I think it is at least as good
as the website
>>>>> we
>>>>>>>> have
>>>>>>>>>> today.
>>>>>>>>>>>> 
>>>>>>>>>>>> Romain Manni-Bucau
>>>>>>>>>>>> @rmannibucau <https://twitter.com/rmannibucau>
|  Blog <
>>>>>>>>>> https://rmannibucau.metawerx.net/> | Old Blog
<
>>>>>>>>>> http://rmannibucau.wordpress.com/> | Github <
>>>>>>>>>> https://github.com/rmannibucau> | LinkedIn <
>>>>>>>>>> https://www.linkedin.com/in/rmannibucau> | Book
<
>>>>>>>>>> 
>>>>>>>> 
>>>>>> 
>>>>> 
>> https://www.packtpub.com/application-development/java-ee-8-high-performance
>>>>>>>>>>> 
>>>>>>>>>>>> 
>>>>>>>>>>>> Le mer. 12 août 2020 à 14:38, Andrew Wetmore
<
>> andreww@apache.org
>>>>>>>>>> <mailto:andreww@apache.org>> a écrit :
>>>>>>>>>>>> Hi, David!
>>>>>>>>>>>> 
>>>>>>>>>>>> Glad to know you are moving forward.
>>>>>>>>>>>> 
>>>>>>>>>>>> We need, for each project:
>>>>>>>>>>>> 
>>>>>>>>>>>> 
>>>>>>>>>>>> - a formal decision by the PMC approving
the move and the tech
>>>>> you
>>>>>>>>>> are
>>>>>>>>>>>> moving to.
>>>>>>>>>>>> - a Jira ticket for INFRA so we have an audit
trail on what we
>>>>> are
>>>>>>>>>> doing
>>>>>>>>>>>> and when.
>>>>>>>>>>>> 
>>>>>>>>>>>> Thank you for pointing out Antora. I will
add it to our list!
>>>>>>>>>>>> 
>>>>>>>>>>>> I will forward your other questions to our
team, who are much
>> more
>>>>>>>>>>>> knowledgeable than I on the migration. Basically,
whoever picks
>> up
>>>>>>>> your
>>>>>>>>>>>> Jira ticket will facilitate the move. As
far as I know, keeping
>>>>>>>>>> repository
>>>>>>>>>>>> history is not a problem.
>>>>>>>>>>>> 
>>>>>>>>>>>> A good way to contact me/us in near-real-time
is to join
>> #asfinfra
>>>>>> on
>>>>>>>>>> the
>>>>>>>>>>>> ASF Slack channel (https://the-asf.slack.com/
<
>>>>>>>>>> https://the-asf.slack.com/>).
>>>>>>>>>>>> 
>>>>>>>>>>>> I am confident this will go pretty smoothly!
>>>>>>>>>>>> 
>>>>>>>>>>>> Andrew
>>>>>>>>>>>> 
>>>>>>>>>>>> <
>>>>>>>>>> 
>>>>>>>> 
>>>>>> 
>>>>> 
>> https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail
>>>>>>>>>> <
>>>>>>>>>> 
>>>>>>>> 
>>>>>> 
>>>>> 
>> https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail
>>>>>>>>>>>> 
>>>>>>>>>>>> Virus-free.
>>>>>>>>>>>> www.avast.com <http://www.avast.com/>
>>>>>>>>>>>> <
>>>>>>>>>> 
>>>>>>>> 
>>>>>> 
>>>>> 
>> https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail
>>>>>>>>>> <
>>>>>>>>>> 
>>>>>>>> 
>>>>>> 
>>>>> 
>> https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail
>>>>>>>>>>>> 
>>>>>>>>>>>> <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
>>>>>>>>>>>> 
>>>>>>>>>>>> On Wed, Aug 12, 2020 at 2:44 AM David Jencks
<
>>>>>>>> david.a.jencks@gmail.com
>>>>>>>>>> <mailto:david.a.jencks@gmail.com>>
>>>>>>>>>>>> wrote:
>>>>>>>>>>>> 
>>>>>>>>>>>>> Hi Andrew,
>>>>>>>>>>>>> 
>>>>>>>>>>>>> I think I’m going to be setting up
the new Aries website.
>>>>>>>>>>>>> 
>>>>>>>>>>>>> We’re going to use Antora to build
the site.  I’m a bit
>> surprised
>>>>>>>> that
>>>>>>>>>>>>> this tool isn’t on your list of common
site builders, at least
>>>>>> Camel
>>>>>>>>>> and
>>>>>>>>>>>>> Isis use it.
>>>>>>>>>>>>> 
>>>>>>>>>>>>> I’m also going to be working to move
TomEE off of CMS, that
>> site
>>>>> is
>>>>>>>>>> likely
>>>>>>>>>>>>> to be partly Antora and partly something
else.
>>>>>>>>>>>>> 
>>>>>>>>>>>>> Something both projects are interested
in is preserving the
>>>>> history
>>>>>>>>>> of the
>>>>>>>>>>>>> website.  I think this could be done
by running svn2git on the
>>>>>>>>>> appropriate
>>>>>>>>>>>>> svn url, could you help figure out what
that url would be?
>>>>>>>>>>>>> 
>>>>>>>>>>>>> When are you generally available and
what is a good way to
>>>>> contact
>>>>>>>>>> you for
>>>>>>>>>>>>> faster than email questions?
>>>>>>>>>>>>> 
>>>>>>>>>>>>> Thanks
>>>>>>>>>>>>> David Jencks
>>>>>>>>>>>>> 
>>>>>>>>>>>>>> On Aug 4, 2020, at 6:33 AM, Andrew
Wetmore<andreww@apache.org
>>>>>>>>>> <mailto:andreww@apache.org>> wrote:
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> Hi:
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> I am part of the Infrastructure team,
and am writing to ask
>>>>>> whether
>>>>>>>>>> your
>>>>>>>>>>>>>> project is still using the Apache
CMS for your project
>> website.
>>>>> As
>>>>>>>>>> you
>>>>>>>>>>>>>> know, the CMS is reaching end-of-life,
and we need projects to
>>>>>> move
>>>>>>>>>> their
>>>>>>>>>>>>>> websites onto a different option
within the next few weeks.
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> There are several alternatives available,
including those
>> listed
>>>>>> on
>>>>>>>>>> this
>>>>>>>>>>>>>> page [1] on managing project websites.
Infra is assembling a
>>>>> Wiki
>>>>>>>>>> page
>>>>>>>>>>>>> [2]
>>>>>>>>>>>>>> on migrating a website from the CMS,
and is looking forward to
>>>>>>>>>> helping
>>>>>>>>>>>>>> projects with this transition.
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> Please let me know whether your site
is still on the Apache
>> CMS
>>>>>>>>>> and, if
>>>>>>>>>>>>> so,
>>>>>>>>>>>>>> who will be the project point-of-contact
with Infra for the
>>>>>>>>>> migration.
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> Thank you!
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> [1] https://infra.apache.org/project-site.html
<
>>>>>>>>>> https://infra.apache.org/project-site.html>
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> [2]
>>>>>>>>>>>>>> 
>>>>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>> 
>>>>>> 
>>>>> 
>> https://cwiki.apache.org/confluence/display/INFRA/Migrate+your+project+website+from+the+Apache+CMS
>>>>>>>>>> <
>>>>>>>>>> 
>>>>>>>> 
>>>>>> 
>>>>> 
>> https://cwiki.apache.org/confluence/display/INFRA/Migrate+your+project+website+from+the+Apache+CMS
>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> --
>>>>>>>>>>>>>> Andrew Wetmore
>>>>>>>>>>>>>> Technical Writer-Editor
>>>>>>>>>>>>>> Infra
>>>>>>>>>>>>>> *Apache Software Foundation*
>>>>>>>>>>>>>> andreww@apache.org <mailto:andreww@apache.org>
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> <
>>>>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>> 
>>>>>> 
>>>>> 
>> https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail
>>>>>>>>>> <
>>>>>>>>>> 
>>>>>>>> 
>>>>>> 
>>>>> 
>> https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail
>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> Virus-free.
>>>>>>>>>>>>>> www.avast.com <http://www.avast.com/>
>>>>>>>>>>>>>> <
>>>>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>> 
>>>>>> 
>>>>> 
>> https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail
>>>>>>>>>> <
>>>>>>>>>> 
>>>>>>>> 
>>>>>> 
>>>>> 
>> https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail
>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
>>>>>>>>>>>>> 
>>>>>>>>>>>>> 
>>>>>>>>>>>> 
>>>>>>>>>>>> --
>>>>>>>>>>>> Andrew Wetmore
>>>>>>>>>>>> Technical Writer-Editor
>>>>>>>>>>>> Infra
>>>>>>>>>>>> *Apache Software Foundation*
>>>>>>>>>>>> andreww@apache.org <mailto:andreww@apache.org>
>>>>>> 
>>>>>> 
>>>>> 
>>>> 
>>>> 
>>>> --
>>>> *Raymond Augé* <http://www.liferay.com/web/raymond.auge/profile>
>>>> (@rotty3000)
>>>> Senior Software Architect *Liferay, Inc.* <http://www.liferay.com>
>>>> (@Liferay)
>>> 
>> 
>> 


Mime
View raw message