I wanted to ask peoples’ opinions on this issue.
A little background: after 3 people have come to the project fresh, and
tried to
get up and running, they all encountered difficulty with the instructions for
building
and setup of the project. To this end, Vish and I took on the tasks related to
getting this repaired.
The first subtask I took on was ARIA-400. After investigating this
subtask
which relates to synchronization of the specific getting started information,
I looked into how the ariatosca.org <http://ariatosca.org/> site is built and
how it relates to
the main code repo.
For reference, there are two GitHub repos in question are:
This is a mirror of apache’s repo for the code of the project:
https://github.com/apache/incubator-ariatosca
<https://github.com/apache/incubator-ariatosca>
This is a set of self-contained, Jekyll/static web pages. These are reflected
(i.e.: copied)
over to the apache site when PRs are merged:
https://github.com/apache/incubator-ariatosca-website
<https://github.com/apache/incubator-ariatosca-website>
The problem I discovered is that the contents of the main README file:
https://github.com/apache/incubator-ariatosca/blob/master/README.rst
<https://github.com/apache/incubator-ariatosca/blob/master/README.rst>
has been manually synchronized with its corresponding
file on the *-website:
https://github.com/apache/incubator-ariatosca-website/blob/master/gettingstarted.md
<https://github.com/apache/incubator-ariatosca-website/blob/master/gettingstarted.md>
So what has happened over time, is that these two files have
effectively diverged, and require some manual intervention. I looked into
options
for doing auto-sync after PRs are pushed to either repo (both have CI processes
setup), but I think that a simpler solution is to simply have either of the
files
refer to the other, effectively keeping on as the “master of record”. In
summary,
these are the options, so I’d like to get some feedback before taking action on
this:
1) Make the incubator-ariatosca/README.rst point at the file that is on
the incubator-ariatosca-website/gettingstarted.md (and others).
Put comments instructing anyone wishing to modify the
README.rst file
to push changes into the other file/s.
2) The inverse of 1.
My preference would be for 1
Thanks,
—Tom
