[PROPOSAL] restructuring build documentation

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

[PROPOSAL] restructuring build documentation

Arrigo Marchiori
Dear All,

I am cross-posting to dev@ and doc@ because... I am not sure which one
fits best. Please excuse me if this is wrong, and only reply on the
correct list.

I personally find building OpenOffice a bit too difficult today, in
terms of _understanding_ what needs to be done. We have build
instructions on the Wiki, build scripts on a SVN repository, but IMHO
a little ``integration'' among these pieces would help every newcomers
(like me) to get a big picture, complete the first successful build
and start helping with the code.

Here are my ideas. I don't know if these topics were already discussed
before my subscription to this list; if so, kindly send me a pointer
so I can avoid you repeating ideas that are already consolidated.

I would like to propose the following layout on the Wiki:

  - build instructions for trunk (currently
    https://wiki.openoffice.org/wiki/Documentation/Building_Guide_AOO
    that needs some updating anyway, such as removing SVN)

    - specialized build instructions for trunk on individual
      O.S. (Linux, Windows, BSD etc)

 - build instructions for the latest release (4.1.8)

    - specialized build instructions for the latest release on
      individual O.S.

The distinction between trunk and release is IMHO necessary. For
example, Jim is doing a very good work of updating core parts of the
build system, and this changes for one the initial call to the
configure script.  In addition, deprecated information such as the SVN
repository could be deleted from the trunk build instructions, and
only remain in the once-applicable instructions.

The current build scripts on SVN should be explicitly indicated in the
instructions, so that everyone will be able to get (almost) the exact
same release build, as what they can download from the web site.

Moreover, having very clear instructions could make DevOps experience
useful, if we ever need it. For those subscribed to the recruitment
mailing list: yes, I am referring to a recent email received
there. :-)

When a new release is out, a ``snapshot'' of the trunk build
instructions will become the release's build instructions. Similarly
to a git or SVN branch. The trunk instructions always document... the
trunk.

If the above is approved, I will be willing to help achieving it. The
roadmap I can think of is the following:

 1- copy the current build instructions to a "release" build
 instructions page.

 2- fix the "release" build pages (starting from going back in the
 page history) so that they contain the actual steps to build AOO
 4.1.8.

 3- remove outdated parts from the trunk build instructions (such as
 the SVN repository)

Thank you in advance for your feedback and comments!

Best regards,
--
rigo

http://rigo.altervista.org

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [PROPOSAL] restructuring build documentation

Mechtilde Stehmann-2
Hello Arrigo,

a very big ++1

so far I had the problem how to begin with the restructure.

After you start I can try to put in my description how to build under
Debian 9 (Stretch) and (if it works) under Debian 10 (buster) with java 11.

Regards

Am 17.12.20 um 14:05 schrieb Arrigo Marchiori:

> Dear All,
>
> I am cross-posting to dev@ and doc@ because... I am not sure which one
> fits best. Please excuse me if this is wrong, and only reply on the
> correct list.
>
> I personally find building OpenOffice a bit too difficult today, in
> terms of _understanding_ what needs to be done. We have build
> instructions on the Wiki, build scripts on a SVN repository, but IMHO
> a little ``integration'' among these pieces would help every newcomers
> (like me) to get a big picture, complete the first successful build
> and start helping with the code.
>
> Here are my ideas. I don't know if these topics were already discussed
> before my subscription to this list; if so, kindly send me a pointer
> so I can avoid you repeating ideas that are already consolidated.
>
> I would like to propose the following layout on the Wiki:
>
>   - build instructions for trunk (currently
>     https://wiki.openoffice.org/wiki/Documentation/Building_Guide_AOO
>     that needs some updating anyway, such as removing SVN)
>
>     - specialized build instructions for trunk on individual
>       O.S. (Linux, Windows, BSD etc)
>
>  - build instructions for the latest release (4.1.8)
>
>     - specialized build instructions for the latest release on
>       individual O.S.
>
> The distinction between trunk and release is IMHO necessary. For
> example, Jim is doing a very good work of updating core parts of the
> build system, and this changes for one the initial call to the
> configure script.  In addition, deprecated information such as the SVN
> repository could be deleted from the trunk build instructions, and
> only remain in the once-applicable instructions.
>
> The current build scripts on SVN should be explicitly indicated in the
> instructions, so that everyone will be able to get (almost) the exact
> same release build, as what they can download from the web site.
>
> Moreover, having very clear instructions could make DevOps experience
> useful, if we ever need it. For those subscribed to the recruitment
> mailing list: yes, I am referring to a recent email received
> there. :-)
>
> When a new release is out, a ``snapshot'' of the trunk build
> instructions will become the release's build instructions. Similarly
> to a git or SVN branch. The trunk instructions always document... the
> trunk.
>
> If the above is approved, I will be willing to help achieving it. The
> roadmap I can think of is the following:
>
>  1- copy the current build instructions to a "release" build
>  instructions page.
>
>  2- fix the "release" build pages (starting from going back in the
>  page history) so that they contain the actual steps to build AOO
>  4.1.8.
>
>  3- remove outdated parts from the trunk build instructions (such as
>  the SVN repository)
>
> Thank you in advance for your feedback and comments!
>
> Best regards,
> --
> rigo
>
> http://rigo.altervista.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
--
Mechtilde Stehmann
## Apache OpenOffice
## Freie Office Suite für Linux, MacOSX, Windows und OS/2
## Debian Developer
## PGP encryption welcome
## F0E3 7F3D C87A 4998 2899  39E7 F287 7BBA 141A AD7F


OpenPGP_signature (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [PROPOSAL] restructuring build documentation

Peter Kovacs-3
In reply to this post by Arrigo Marchiori
sure, try what you have in mind.

We wont loose anything by trying.


On 17.12.20 14:05, Arrigo Marchiori wrote:

> Dear All,
>
> I am cross-posting to dev@ and doc@ because... I am not sure which one
> fits best. Please excuse me if this is wrong, and only reply on the
> correct list.
>
> I personally find building OpenOffice a bit too difficult today, in
> terms of _understanding_ what needs to be done. We have build
> instructions on the Wiki, build scripts on a SVN repository, but IMHO
> a little ``integration'' among these pieces would help every newcomers
> (like me) to get a big picture, complete the first successful build
> and start helping with the code.
>
> Here are my ideas. I don't know if these topics were already discussed
> before my subscription to this list; if so, kindly send me a pointer
> so I can avoid you repeating ideas that are already consolidated.
>
> I would like to propose the following layout on the Wiki:
>
>    - build instructions for trunk (currently
>      https://wiki.openoffice.org/wiki/Documentation/Building_Guide_AOO
>      that needs some updating anyway, such as removing SVN)
>
>      - specialized build instructions for trunk on individual
>        O.S. (Linux, Windows, BSD etc)
>
>   - build instructions for the latest release (4.1.8)
>
>      - specialized build instructions for the latest release on
>        individual O.S.
>
> The distinction between trunk and release is IMHO necessary. For
> example, Jim is doing a very good work of updating core parts of the
> build system, and this changes for one the initial call to the
> configure script.  In addition, deprecated information such as the SVN
> repository could be deleted from the trunk build instructions, and
> only remain in the once-applicable instructions.
>
> The current build scripts on SVN should be explicitly indicated in the
> instructions, so that everyone will be able to get (almost) the exact
> same release build, as what they can download from the web site.
>
> Moreover, having very clear instructions could make DevOps experience
> useful, if we ever need it. For those subscribed to the recruitment
> mailing list: yes, I am referring to a recent email received
> there. :-)
>
> When a new release is out, a ``snapshot'' of the trunk build
> instructions will become the release's build instructions. Similarly
> to a git or SVN branch. The trunk instructions always document... the
> trunk.
>
> If the above is approved, I will be willing to help achieving it. The
> roadmap I can think of is the following:
>
>   1- copy the current build instructions to a "release" build
>   instructions page.
>
>   2- fix the "release" build pages (starting from going back in the
>   page history) so that they contain the actual steps to build AOO
>   4.1.8.
>
>   3- remove outdated parts from the trunk build instructions (such as
>   the SVN repository)
>
> Thank you in advance for your feedback and comments!
>
> Best regards,
> --
> rigo
>
> http://rigo.altervista.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
--
This is the Way! http://www.apache.org/theapacheway/index.html

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [PROPOSAL] restructuring build documentation

Dave Fisher-2
In reply to this post by Arrigo Marchiori
Hi Arrigo,

I really appreciate your enthusiasm and excellent help on AOO!

There was another thread where we discussed moving devtools to git.

I think this would be the perfect time to move/rewrite build instructions as markdown files on these GitHub repos:

Apache/openoffice - README.md
Apache/openoffice-project source.md
A new Apache/openoffice-devtools

I would deprecate the Wiki instructions.

Regards,
Dave

> On Dec 17, 2020, at 5:05 AM, Arrigo Marchiori <[hidden email]> wrote:
>
> Dear All,
>
> I am cross-posting to dev@ and doc@ because... I am not sure which one
> fits best. Please excuse me if this is wrong, and only reply on the
> correct list.
>
> I personally find building OpenOffice a bit too difficult today, in
> terms of _understanding_ what needs to be done. We have build
> instructions on the Wiki, build scripts on a SVN repository, but IMHO
> a little ``integration'' among these pieces would help every newcomers
> (like me) to get a big picture, complete the first successful build
> and start helping with the code.
>
> Here are my ideas. I don't know if these topics were already discussed
> before my subscription to this list; if so, kindly send me a pointer
> so I can avoid you repeating ideas that are already consolidated.
>
> I would like to propose the following layout on the Wiki:
>
>  - build instructions for trunk (currently
>    https://wiki.openoffice.org/wiki/Documentation/Building_Guide_AOO
>    that needs some updating anyway, such as removing SVN)
>
>    - specialized build instructions for trunk on individual
>      O.S. (Linux, Windows, BSD etc)
>
> - build instructions for the latest release (4.1.8)
>
>    - specialized build instructions for the latest release on
>      individual O.S.
>
> The distinction between trunk and release is IMHO necessary. For
> example, Jim is doing a very good work of updating core parts of the
> build system, and this changes for one the initial call to the
> configure script.  In addition, deprecated information such as the SVN
> repository could be deleted from the trunk build instructions, and
> only remain in the once-applicable instructions.
>
> The current build scripts on SVN should be explicitly indicated in the
> instructions, so that everyone will be able to get (almost) the exact
> same release build, as what they can download from the web site.
>
> Moreover, having very clear instructions could make DevOps experience
> useful, if we ever need it. For those subscribed to the recruitment
> mailing list: yes, I am referring to a recent email received
> there. :-)
>
> When a new release is out, a ``snapshot'' of the trunk build
> instructions will become the release's build instructions. Similarly
> to a git or SVN branch. The trunk instructions always document... the
> trunk.
>
> If the above is approved, I will be willing to help achieving it. The
> roadmap I can think of is the following:
>
> 1- copy the current build instructions to a "release" build
> instructions page.
>
> 2- fix the "release" build pages (starting from going back in the
> page history) so that they contain the actual steps to build AOO
> 4.1.8.
>
> 3- remove outdated parts from the trunk build instructions (such as
> the SVN repository)
>
> Thank you in advance for your feedback and comments!
>
> Best regards,
> --
> rigo
>
> http://rigo.altervista.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [PROPOSAL] restructuring build documentation

Arrigo Marchiori
Hello Dave,

On Thu, Dec 17, 2020 at 11:09:15AM -0800, Dave Fisher wrote:

> Hi Arrigo,
>
> I really appreciate your enthusiasm and excellent help on AOO!

Thank you! I am just doing what I can.

> There was another thread where we discussed moving devtools to git.

I think you mean this one?
https://lists.apache.org/thread.html/r64090cf9de98c0147098b5d7d58b5f248c71b42e06d3dcb1c536bc88%40%3Cdev.openoffice.apache.org%3E

> I think this would be the perfect time to move/rewrite build instructions as
markdown files on these GitHub repos:
>
> Apache/openoffice - README.md
> Apache/openoffice-project source.md
> A new Apache/openoffice-devtools
>
> I would deprecate the Wiki instructions.

I think I get your point. This would ensure that the doc is always
paired with the software it talks about.

However, I suggest to keep this documentation on the Wiki, at least at
a first stage. I think it is quicker and easier to edit, and better
allows people to cooperate on the same document, than using Git and
pull requests.

When finished, the ``snapshots'' could be saved into the source tree
when a release is published, and this could avoid us ``branches'' on
the wiki as well as on the code.  But I would leave such decision to a
later stage.

I hope this makes sense.

Best regards,
--
rigo

http://rigo.altervista.org

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [PROPOSAL] restructuring build documentation

Arrigo Marchiori
Dear dev@ and doc@ lists,

this message is to inform you that I am (slowly) beginning to put my
proposal in action.

There is a thread on dev@ that is about archiving old web pages, that
is currently on hold for the holiday time. I will _not_ wait for that
thread to reach a conclusion, because I honestly believe that
archiving build instructions for individual releases does not really
fit in the purpose of that thread.

If anyone thinks that I am wrong, and that I should instead wait until
that thread has come to a conclusion, then please just tell me, and I
will stop and revert any changes. I am just trying not to lose time,
in the interest of the project.

I take the occasion to wish a happy 2021 to everybody!
--
Arrigo

http://rigo.altervista.org

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]