You are viewing a plain text version of this content. The canonical link for it is here.
Posted to doc@openoffice.apache.org by Dennis Hamilton <or...@msn.com> on 2021/02/03 17:06:23 UTC
Repository Organization
There is only one project for all of it, so it is not clear how well the handling of multiple guides and other publications can be sequenced and synchronized. Unfortunately, a check-out at this level will bring everything to a contributor's computer. I don't know if there is a finer-grained way to handle this. It would be worth investigating. Most top-level GitHub projects provide multiple (sub-) projects so coordination is better. However, github.com/apache/ is that level so such capability is already taken [;<).
A subdirectory structure that has a folder for each guide or other publication, and maybe folders on templates and other materials for authors/editors would be helpful. If these are actually (sub-) projects, working is even easier. There could still be subfolders on released, draft, or however you want to do that.
It is possible to **label** *releases* rather than use branches for that purpose. Also, it is better to branch at the individual document level, so maybe the branch name would specify what guide is being worked on in that branch. When a document continues to be applicable to a newer release, one could simply tag it for that release as well. There will need to be ground rules about this that are clear enough people don't do pushes against the wrong branches, etc. The value is that you don't have to update all the documents for every dot-dot-release and interested parties can look at just the Getting Started, or the Writer document or whatever, and know what multiple releases the current one applies to. You may need to have language as part of the substructure also, not just platform, however those varieties are to be handled.
Sometimes, when the impact of a release is minor, one might one to provide a companion supplement to a full guide, also tagged for that release.
There are many GitHub projects that can be inspected for how this sort of thing is done. < https://github.com/MicrosoftDocs> is one example although I think the organization can be more thoughtful when focus is on AOO docs. Carl Marcum must know of some approaches related to work he has done.
If you have the rights, you can also enable Issues, Discussion and even Wiki for the openoffice-docs project. You can then work out matters there in a form that is easier and more organized than using docs @ oo.a.o threads as a coordination mechanism.
Happy day-after USA Ground Hog Day. We have passed to the other side.
- Dennis
PS: I still think you need to look at and consult Community Forum folk. There is a significant amount of experience there and it is almost all (power-) user facing.
-----Original Message-----
From: Keith N. McKenna <ke...@comcast.net>
Sent: Wednesday, February 3, 2021 07:20
To: doc@openoffice.apache.org
Subject: Repository has been created
I got word earlier from Carl Marcum that the repository https://github.com/apache/openoffice-docs has been created. It is pretty sparse at the moment as there is only the README.md file from my repo on GitHub.
The next step is to define the the branches. Do we want a separate branch for each release of the the software for example 4.1.9, 4.1.10 or just for the major.minor, for example 4.1, 4.2 etc.
The branch for each release has the potential to create more work in that we could be creating new documentation that has few if any changes to the previous versions.
The major.minor branching creates the reverse possibility. We could
**not** produce documents when it was warranted.
Please reply with any suggestions for either of the schemes above and if you have an idea for something else.
Regards
Keith
RE: Repository Organization
Posted by Dennis Hamilton <or...@msn.com>.
When you go to <https://github.com/apache/openoffice-docs>, can you see the settings option on the right end of the menu strip (the one with <> code at the top left)?
If so, you can do those things yourself.
If not, you need infra for such stuff. Or maybe you can do it in-project. Or be granted some rights.
There may be membership requirements to be in the Apache GitHub group as well.
- Dennis
-----Original Message-----
From: Keith N. McKenna <ke...@comcast.net>
Sent: Thursday, February 4, 2021 15:47
To: doc@openoffice.apache.org
Subject: Re: Repository Organization
[ ... ]
> If you have the rights, you can also enable Issues, Discussion and
> even Wiki for the openoffice-docs project. You can then work out
> matters there in a form that is easier and more organized than using
> docs @ oo.a.o threads as a coordination mechanism.
I am not sure of these but do warrant a discussion with infra as to the possibility of using some.
Regards
Keith
[...]
Re: Repository Organization
Posted by "Keith N. McKenna" <ke...@comcast.net>.
Hi Dennis
On 2/3/2021 12:06 PM, Dennis Hamilton wrote:
> There is only one project for all of it, so it is not clear how well
> the handling of multiple guides and other publications can be
> sequenced and synchronized. Unfortunately, a check-out at this level
> will bring everything to a contributor's computer. I don't know if
> there is a finer-grained way to handle this. It would be worth
> investigating. Most top-level GitHub projects provide multiple
> (sub-) projects so coordination is better. However,
> github.com/apache/ is that level so such capability is already taken
> [;<).
>
The logic behind using branches with the 2 directories is to handle the
draft->edit cycle prior to publication. The same person cannot be author
and editor on the same document or chapter. Using the Review folder for
that initial cycle helps alleviate that issue.
> A subdirectory structure that has a folder for each guide or other
> publication, and maybe folders on templates and other materials for
> authors/editors would be helpful. If these are actually (sub-)
> projects, working is even easier. There could still be subfolders on
> released, draft, or however you want to do that.
>
I am not understanding your use ob sub-projects here Dennis.According to
the GitHub documentation, a sub-project developed outside of the main
project and pulled in as needed, thus alleviating the need for the
project to maintain the code itself. That would not be the case here, as
we are maintaining the docs in house.
> It is possible to **label** *releases* rather than use branches for
> that purpose. Also, it is better to branch at the individual
> document level, so maybe the branch name would specify what guide is
> being worked on in that branch. When a document continues to be
> applicable to a newer release, one could simply tag it for that
> release as well. There will need to be ground rules about this that
> are clear enough people don't do pushes against the wrong branches,
> etc. The value is that you don't have to update all the documents
> for every dot-dot-release and interested parties can look at just the
> Getting Started, or the Writer document or whatever, and know what
> multiple releases the current one applies to. You may need to have
> language as part of the substructure also, not just platform, however
> those varieties are to be handled.
>
I can see branching at the software version using a branch for each
guide, but it would still require 2 sub-folders to separate the
in-process things from the published material. Also folders for
translations are not something I had thought of.
> Sometimes, when the impact of a release is minor, one might one to
> provide a companion supplement to a full guide, also tagged for that
> release.
Supplying errata is also a good idea.
>
> There are many GitHub projects that can be inspected for how this
> sort of thing is done. < https://github.com/MicrosoftDocs> is one
> example although I think the organization can be more thoughtful when
> focus is on AOO docs. Carl Marcum must know of some approaches
> related to work he has done.
>
> If you have the rights, you can also enable Issues, Discussion and
> even Wiki for the openoffice-docs project. You can then work out
> matters there in a form that is easier and more organized than using
> docs @ oo.a.o threads as a coordination mechanism.
I am not sure of these but do warrant a discussion with infra as to the
possibility of using some.
Regards
Keith
>
> Happy day-after USA Ground Hog Day. We have passed to the other
> side.
>
> - Dennis
>
> PS: I still think you need to look at and consult Community Forum
> folk. There is a significant amount of experience there and it is
> almost all (power-) user facing.
>
>
> -----Original Message----- From: Keith N. McKenna
> <ke...@comcast.net> Sent: Wednesday, February 3, 2021 07:20
> To: doc@openoffice.apache.org Subject: Repository has been created
>
> I got word earlier from Carl Marcum that the repository
> https://github.com/apache/openoffice-docs has been created. It is
> pretty sparse at the moment as there is only the README.md file from
> my repo on GitHub.
>
> The next step is to define the the branches. Do we want a separate
> branch for each release of the the software for example 4.1.9, 4.1.10
> or just for the major.minor, for example 4.1, 4.2 etc.
>
> The branch for each release has the potential to create more work in
> that we could be creating new documentation that has few if any
> changes to the previous versions.
>
> The major.minor branching creates the reverse possibility. We could
> **not** produce documents when it was warranted.
>
> Please reply with any suggestions for either of the schemes above and
> if you have an idea for something else.
>
> Regards Keith
>
>
>
>
>
>
>
> ---------------------------------------------------------------------
>
>
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
> For additional commands, e-mail: doc-help@openoffice.apache.org
>
RE: Repository Organization
Posted by or...@msn.com.
Yes, it appears that GitHub Projects are amenable for managing workflow and
coordinating the documentation. Ideally, you want Issues (because they can be
tied into commit messages and vice versa), discussions (ditto), and Projects.
- Dennis
-----Original Message-----
From: Keith N. McKenna <ke...@comcast.net>
Sent: Friday, February 5, 2021 13:07
To: doc@openoffice.apache.org
Subject: Re: Repository Organization
On 2/5/2021 3:10 PM, Dave wrote:
>
> Would a Document/Chapter "Status" spreadsheet be a possible option?
> Whereby a contributor "checks out" a file they will be working on by
> updating the spreadsheet and updates again upon returning the file.
>
That could work, the other thing I was thinking was checking with infra if
GitHub projects can be used in our repository and using that to track who is
doing what.
Regards
Keith
> On 05/02/2021 19:29, Dennis Hamilton wrote:
>> Oh. I would have thought the starting base documents would go in there
>> first. Under an OOo3.2 or something.
>>
>> How are Frances and Marcia avoiding collisions and/or duplication ?
>>
>> -----Original Message-----
>> From: Keith N. McKenna <ke...@comcast.net>
>> Sent: Friday, February 5, 2021 10:30
>> To: doc@openoffice.apache.org
>> Subject: Re: Repository Organization
>>
>> [orcmid] [ ... ]
>>
>> Both Frances and Marcia are marking up possible changes to Jean's taming
>> aoo book and nothing is in the repository yet as it was just created a
>> couple of days ago.
>>
>> Regards
>> Keith
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org
Re: Repository Organization
Posted by "Keith N. McKenna" <ke...@comcast.net>.
On 2/5/2021 3:10 PM, Dave wrote:
>
> Would a Document/Chapter "Status" spreadsheet be a possible option?
> Whereby a contributor "checks out" a file they will be working on by
> updating the spreadsheet and updates again upon returning the file.
>
That could work, the other thing I was thinking was checking with infra
if GitHub projects can be used in our repository and using that to track
who is doing what.
Regards
Keith
> On 05/02/2021 19:29, Dennis Hamilton wrote:
>> Oh. I would have thought the starting base documents would go in there first. Under an OOo3.2 or something.
>>
>> How are Frances and Marcia avoiding collisions and/or duplication ?
>>
>> -----Original Message-----
>> From: Keith N. McKenna <ke...@comcast.net>
>> Sent: Friday, February 5, 2021 10:30
>> To: doc@openoffice.apache.org
>> Subject: Re: Repository Organization
>>
>> [orcmid] [ ... ]
>>
>> Both Frances and Marcia are marking up possible changes to Jean's taming aoo book and nothing is in the repository yet as it was just created a couple of days ago.
>>
>> Regards
>> Keith
Re: Repository Organization
Posted by Jean Weber <je...@gmail.com>.
I just saw this, after writing my previous note. In addition to what I
said there (about chapter files),
* Yes, please change the name of the book and other info as required.
* No, I don't plan to continue working on it myself.
Jean
On Sat, Feb 6, 2021 at 7:01 AM Keith N. McKenna
<ke...@comcast.net> wrote:
>
> I am going to ping Jean and see if she has chapter files available as
> well as the single guide as that would be much easier to deal with as we
> need to change the tittle and other things unless she wants us to
> contribute to what she is doing and give us credit as contributes.
>
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org
Re: Repository Organization
Posted by "Keith N. McKenna" <ke...@comcast.net>.
On 2/5/2021 3:21 PM, F Campos Costero wrote:
> At the moment, I am only planning changes by inserting comments. Some of
> the images need to be updated, there are a few erroneous statements, and
> there are some out-of-date statements that should be revised or deleted. I
> hope to hold off on real editing until I see what Marcia has done, which
> she hopes to post tomorrow. She and I will have to coordinate, probably by
> chapter, if we will both be working on Taming.
> I had also thought of using a tracking document so people can record what
> they are working on. Most of the guides are available as standalone
> chapters, so one could have a reasonably granular view of the work in
> progress.
I am going to ping Jean and see if she has chapter files available as
well as the single guide as that would be much easier to deal with as we
need to change the tittle and other things unless she wants us to
contribute to what she is doing and give us credit as contributes.
>
> I think all of the 3.3 user guides could be loaded in the repository at
> this point. I would be surprised if I can push to the repository or create
> branches, I have no official Apache status and I suppose random people are
> not allowed to do such things.
>
I will be starting that as it seems the consensus is to branch by Guide
rather than software version. I am also going to be checking with infra
if we can activate projects on the repository so we can
> Francis
>
> On Fri, Feb 5, 2021 at 1:10 PM Dave <bm...@apache.org> wrote:
>
>>
>> Would a Document/Chapter "Status" spreadsheet be a possible option?
>> Whereby a contributor "checks out" a file they will be working on by
>> updating the spreadsheet and updates again upon returning the file.
>>
>> On 05/02/2021 19:29, Dennis Hamilton wrote:
>>> Oh. I would have thought the starting base documents would go in there
>> first. Under an OOo3.2 or something.
>>>
>>> How are Frances and Marcia avoiding collisions and/or duplication ?
>>>
>>> -----Original Message-----
>>> From: Keith N. McKenna <ke...@comcast.net>
>>> Sent: Friday, February 5, 2021 10:30
>>> To: doc@openoffice.apache.org
>>> Subject: Re: Repository Organization
>>>
>>> [orcmid] [ ... ]
>>>
>>> Both Frances and Marcia are marking up possible changes to Jean's taming
>> aoo book and nothing is in the repository yet as it was just created a
>> couple of days ago.
>>>
>>> Regards
>>> Keith
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
>> For additional commands, e-mail: doc-help@openoffice.apache.org
>>
>>
RE: Repository Organization
Posted by or...@msn.com.
Anyone can fork the repo on GitHub. That's better for working in the open on
the side of the project. Then work can be pushed (via pull request) to the
Apache/openoffice-docs repo. Someone with authority over integration of
requested pushes does the final integration. People can also review the pull
request and comment on it before action is taken.
I don't recommend cloning the repository directly. You probably cannot sync
directly to it. But you can clone from a fork to your computer, keep them
synchronized as you make edits, and then push from the fork to the original
when ready. There is a procedure for updating your fork from changes to the
official repo.
This is all a bit geeky. It comes with choosing to use git in the open. It
works better with diff-able text files rather than ODF Packages [;<).
- Dennis
-----Original Message-----
From: F Campos Costero <fj...@gmail.com>
Sent: Friday, February 5, 2021 12:22
To: doc@openoffice.apache.org
Subject: Re: Repository Organization
At the moment, I am only planning changes by inserting comments. Some of the
images need to be updated, there are a few erroneous statements, and there are
some out-of-date statements that should be revised or deleted. I hope to hold
off on real editing until I see what Marcia has done, which she hopes to post
tomorrow. She and I will have to coordinate, probably by chapter, if we will
both be working on Taming.
I had also thought of using a tracking document so people can record what they
are working on. Most of the guides are available as standalone chapters, so
one could have a reasonably granular view of the work in progress.
I think all of the 3.3 user guides could be loaded in the repository at this
point. I would be surprised if I can push to the repository or create
branches, I have no official Apache status and I suppose random people are not
allowed to do such things.
Francis
On Fri, Feb 5, 2021 at 1:10 PM Dave <bm...@apache.org> wrote:
>
> Would a Document/Chapter "Status" spreadsheet be a possible option?
> Whereby a contributor "checks out" a file they will be working on by
> updating the spreadsheet and updates again upon returning the file.
>
> On 05/02/2021 19:29, Dennis Hamilton wrote:
> > Oh. I would have thought the starting base documents would go in
> > there
> first. Under an OOo3.2 or something.
> >
> > How are Frances and Marcia avoiding collisions and/or duplication ?
> >
> > -----Original Message-----
> > From: Keith N. McKenna <ke...@comcast.net>
> > Sent: Friday, February 5, 2021 10:30
> > To: doc@openoffice.apache.org
> > Subject: Re: Repository Organization
> >
> > [orcmid] [ ... ]
> >
> > Both Frances and Marcia are marking up possible changes to Jean's
> > taming
> aoo book and nothing is in the repository yet as it was just created a
> couple of days ago.
> >
> > Regards
> > Keith
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
> For additional commands, e-mail: doc-help@openoffice.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org
Re: Repository Organization
Posted by F Campos Costero <fj...@gmail.com>.
At the moment, I am only planning changes by inserting comments. Some of
the images need to be updated, there are a few erroneous statements, and
there are some out-of-date statements that should be revised or deleted. I
hope to hold off on real editing until I see what Marcia has done, which
she hopes to post tomorrow. She and I will have to coordinate, probably by
chapter, if we will both be working on Taming.
I had also thought of using a tracking document so people can record what
they are working on. Most of the guides are available as standalone
chapters, so one could have a reasonably granular view of the work in
progress.
I think all of the 3.3 user guides could be loaded in the repository at
this point. I would be surprised if I can push to the repository or create
branches, I have no official Apache status and I suppose random people are
not allowed to do such things.
Francis
On Fri, Feb 5, 2021 at 1:10 PM Dave <bm...@apache.org> wrote:
>
> Would a Document/Chapter "Status" spreadsheet be a possible option?
> Whereby a contributor "checks out" a file they will be working on by
> updating the spreadsheet and updates again upon returning the file.
>
> On 05/02/2021 19:29, Dennis Hamilton wrote:
> > Oh. I would have thought the starting base documents would go in there
> first. Under an OOo3.2 or something.
> >
> > How are Frances and Marcia avoiding collisions and/or duplication ?
> >
> > -----Original Message-----
> > From: Keith N. McKenna <ke...@comcast.net>
> > Sent: Friday, February 5, 2021 10:30
> > To: doc@openoffice.apache.org
> > Subject: Re: Repository Organization
> >
> > [orcmid] [ ... ]
> >
> > Both Frances and Marcia are marking up possible changes to Jean's taming
> aoo book and nothing is in the repository yet as it was just created a
> couple of days ago.
> >
> > Regards
> > Keith
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
> For additional commands, e-mail: doc-help@openoffice.apache.org
>
>
Re: Repository Organization
Posted by Dave <bm...@apache.org>.
Would a Document/Chapter "Status" spreadsheet be a possible option?
Whereby a contributor "checks out" a file they will be working on by
updating the spreadsheet and updates again upon returning the file.
On 05/02/2021 19:29, Dennis Hamilton wrote:
> Oh. I would have thought the starting base documents would go in there first. Under an OOo3.2 or something.
>
> How are Frances and Marcia avoiding collisions and/or duplication ?
>
> -----Original Message-----
> From: Keith N. McKenna <ke...@comcast.net>
> Sent: Friday, February 5, 2021 10:30
> To: doc@openoffice.apache.org
> Subject: Re: Repository Organization
>
> [orcmid] [ ... ]
>
> Both Frances and Marcia are marking up possible changes to Jean's taming aoo book and nothing is in the repository yet as it was just created a couple of days ago.
>
> Regards
> Keith
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org
Re: Repository Organization
Posted by "Keith N. McKenna" <ke...@comcast.net>.
On 2/5/2021 2:29 PM, Dennis Hamilton wrote:
> Oh. I would have thought the starting base documents would go in there first. Under an OOo3.2 or something.
I am not sure whether to do that and add more branches to the repository
or as people are ready to work on a chapter have them download it from
the wiki. Probably best to have them in the repository.
>
> How are Frances and Marcia avoiding collisions and/or duplication ?
No clue neither has shared there work so far. Though she did say she
would push it soon.
Regards
Keith
>
> -----Original Message-----
> From: Keith N. McKenna <ke...@comcast.net>
> Sent: Friday, February 5, 2021 10:30
> To: doc@openoffice.apache.org
> Subject: Re: Repository Organization
>
> [orcmid] [ ... ]
>
> Both Frances and Marcia are marking up possible changes to Jean's taming aoo book and nothing is in the repository yet as it was just created a couple of days ago.
>
> Regards
> Keith
>
> [ ... ]
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
> For additional commands, e-mail: doc-help@openoffice.apache.org
>
RE: Repository Organization
Posted by Dennis Hamilton <or...@msn.com>.
Oh. I would have thought the starting base documents would go in there first. Under an OOo3.2 or something.
How are Frances and Marcia avoiding collisions and/or duplication ?
-----Original Message-----
From: Keith N. McKenna <ke...@comcast.net>
Sent: Friday, February 5, 2021 10:30
To: doc@openoffice.apache.org
Subject: Re: Repository Organization
[orcmid] [ ... ]
Both Frances and Marcia are marking up possible changes to Jean's taming aoo book and nothing is in the repository yet as it was just created a couple of days ago.
Regards
Keith
[ ... ]
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org
Re: Repository Organization
Posted by "Keith N. McKenna" <ke...@comcast.net>.
On 2/5/2021 12:32 PM, Dennis Hamilton wrote:
> Keep in mind that branching happens at the project/repository level. That is, a branch is always of the *entire* repository in some (branch) state.
>
> I think my main point is that repository organization should be by document, since there is no way to do all the documents in lockstep with AOO dot releases. There does not seem to be any capacity for the level of effort that would require.
I am seeing that point as well and will most likely do it that way
rather than by what software release.
>
> The tricky part, since you can't go finer other than by external agreement (e.g., naming branches to identify the guide and release they apply to, say), is figuring out how to resolve pushes of changes to different guides that are collisions at the repo level. Collisions in the same guide are presumably reconcilable, although/because there is no diff for ODF-format files. It's all or nothing or whatever adjustments happen off-line before a change is made to the branch in the main repo.
The way around that I see is to do the guide by chapter then assemble it
a single document when all the chapters are completed.
>
> Big projects have organizations structures among editors/captains/committers to help manage the review and roll-up of changes. Git was invented to facilitate that with an organized hierarchy for the march of changes into a new release (e.g., for Linux itself).
>
> With regard to the work that Francis is doing, is it showing up on the repository or are folks reporting what they are doing entirely off-line?
>
Both Frances and Marcia are marking up possible changes to Jean's taming
aoo book and nothing is in the repository yet as it was just created a
couple of days ago.
Regards
Keith
> - Dennis
>
> -----Original Message-----
> From: Keith N. McKenna <ke...@comcast.net>
> Sent: Thursday, February 4, 2021 16:46
> To: doc@openoffice.apache.org
> Subject: Re: Repository Organization
>
> [orcmid] [ ... ]
>
> It does certainly make sense. I was thinking more along the lines that Dennis outlined and keeping each guide in its own Branch and use tags to specify what revision of the software it applies to. That way if it is applicable to another version as well we tag it that way and not have to redo the entire guide. Also if there are only minor changes we can do errata sheets and not have to redo the entire guide.
>
> regards
> Keith
> [ ... ]
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
> For additional commands, e-mail: doc-help@openoffice.apache.org
>
RE: Repository Organization
Posted by Dennis Hamilton <or...@msn.com>.
Keep in mind that branching happens at the project/repository level. That is, a branch is always of the *entire* repository in some (branch) state.
I think my main point is that repository organization should be by document, since there is no way to do all the documents in lockstep with AOO dot releases. There does not seem to be any capacity for the level of effort that would require.
The tricky part, since you can't go finer other than by external agreement (e.g., naming branches to identify the guide and release they apply to, say), is figuring out how to resolve pushes of changes to different guides that are collisions at the repo level. Collisions in the same guide are presumably reconcilable, although/because there is no diff for ODF-format files. It's all or nothing or whatever adjustments happen off-line before a change is made to the branch in the main repo.
Big projects have organizations structures among editors/captains/committers to help manage the review and roll-up of changes. Git was invented to facilitate that with an organized hierarchy for the march of changes into a new release (e.g., for Linux itself).
With regard to the work that Francis is doing, is it showing up on the repository or are folks reporting what they are doing entirely off-line?
- Dennis
-----Original Message-----
From: Keith N. McKenna <ke...@comcast.net>
Sent: Thursday, February 4, 2021 16:46
To: doc@openoffice.apache.org
Subject: Re: Repository Organization
[orcmid] [ ... ]
It does certainly make sense. I was thinking more along the lines that Dennis outlined and keeping each guide in its own Branch and use tags to specify what revision of the software it applies to. That way if it is applicable to another version as well we tag it that way and not have to redo the entire guide. Also if there are only minor changes we can do errata sheets and not have to redo the entire guide.
regards
Keith
[ ... ]
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org
Re: Repository Organization
Posted by "Keith N. McKenna" <ke...@comcast.net>.
On 2/3/2021 1:49 PM, F Campos Costero wrote:
> I have limited experience with Git, using it only for my own small
> projects, so my opinion should be weighted accordingly. My initial thought
> is to not branch based on releases but to branch on documents. Tagging
> commits as representing a certain AOO release or perhaps as representing a
> certain AOO release with respect to one document would be enough.
>
That is okay Francis I have limited experience with it as well and only
started using it as I conceived of this push to get documentation moving
again. Dennis had said the same thing and I see the efficacy of doing that.
> Am I right in thinking we would have about 15 documents even if everything
> is brought up to date? The documents that come to mind are one guide per
> application (6), the Taming AOO book, some OS specific short guides, and
> the programming guide. I am not sure whether the developer's guide or the
> building guide are part of the doc team's project.
Definitely the Getting Started and a guide for each of the applications.
Beyond that I am not sure.Most of the others you mention are in the wiki
and may best be maintained that way and there is nothing to say that the
documentation team could be *actively involved* in maintaining them.
>
> The work flow I am imagining is to have a branch dedicated to each
> document. When the document is ready to become the latest version, the
> branch is merged into a Main branch that has all of the documents in the
> form in which they appear on the documentation web site. I suppose one
> would update the document-specific branch to the latest version of all the
> other documents just before pushing it to Main, I am not clear on just how
> that would work. None of the public facing documents is ever edited except
> in its own branch. (There might be templates or other administrative
> documents that are handled differently.) Each document-specific branch runs
> on indefinitely since it will always have, in some commit, the
> released version of that document.
>
> Does that make even a little sense?
>
It does certainly make sense. I was thinking more along the lines that
Dennis outlined and keeping each guide in its own Branch and use tags to
specify what revision of the software it applies to. That way if it is
applicable to another version as well we tag it that way and not have to
redo the entire guide. Also if there are only minor changes we can do
errata sheets and not have to redo the entire guide.
regards
Keith
> Francis
>
> On Wed, Feb 3, 2021 at 10:06 AM Dennis Hamilton <or...@msn.com> wrote:
>
>> There is only one project for all of it, so it is not clear how well the
>> handling of multiple guides and other publications can be sequenced and
>> synchronized. Unfortunately, a check-out at this level will bring
>> everything to a contributor's computer. I don't know if there is a
>> finer-grained way to handle this. It would be worth investigating. Most
>> top-level GitHub projects provide multiple (sub-) projects so coordination
>> is better. However, github.com/apache/ is that level so such capability
>> is already taken [;<).
>>
>> A subdirectory structure that has a folder for each guide or other
>> publication, and maybe folders on templates and other materials for
>> authors/editors would be helpful. If these are actually (sub-) projects,
>> working is even easier. There could still be subfolders on released, draft,
>> or however you want to do that.
>>
>> It is possible to **label** *releases* rather than use branches for that
>> purpose. Also, it is better to branch at the individual document level, so
>> maybe the branch name would specify what guide is being worked on in that
>> branch. When a document continues to be applicable to a newer release, one
>> could simply tag it for that release as well. There will need to be ground
>> rules about this that are clear enough people don't do pushes against the
>> wrong branches, etc. The value is that you don't have to update all the
>> documents for every dot-dot-release and interested parties can look at just
>> the Getting Started, or the Writer document or whatever, and know what
>> multiple releases the current one applies to. You may need to have
>> language as part of the substructure also, not just platform, however those
>> varieties are to be handled.
>>
>> Sometimes, when the impact of a release is minor, one might one to provide
>> a companion supplement to a full guide, also tagged for that release.
>>
>> There are many GitHub projects that can be inspected for how this sort of
>> thing is done. < https://github.com/MicrosoftDocs> is one example
>> although I think the organization can be more thoughtful when focus is on
>> AOO docs. Carl Marcum must know of some approaches related to work he has
>> done.
>>
>> If you have the rights, you can also enable Issues, Discussion and even
>> Wiki for the openoffice-docs project. You can then work out matters there
>> in a form that is easier and more organized than using docs @ oo.a.o
>> threads as a coordination mechanism.
>>
>> Happy day-after USA Ground Hog Day. We have passed to the other side.
>>
>> - Dennis
>>
>> PS: I still think you need to look at and consult Community Forum folk.
>> There is a significant amount of experience there and it is almost all
>> (power-) user facing.
>>
>>
>> -----Original Message-----
>> From: Keith N. McKenna <ke...@comcast.net>
>> Sent: Wednesday, February 3, 2021 07:20
>> To: doc@openoffice.apache.org
>> Subject: Repository has been created
>>
>> I got word earlier from Carl Marcum that the repository
>> https://github.com/apache/openoffice-docs has been created. It is pretty
>> sparse at the moment as there is only the README.md file from my repo on
>> GitHub.
>>
>> The next step is to define the the branches. Do we want a separate branch
>> for each release of the the software for example 4.1.9, 4.1.10 or just for
>> the major.minor, for example 4.1, 4.2 etc.
>>
>> The branch for each release has the potential to create more work in that
>> we could be creating new documentation that has few if any changes to the
>> previous versions.
>>
>> The major.minor branching creates the reverse possibility. We could
>> **not** produce documents when it was warranted.
>>
>> Please reply with any suggestions for either of the schemes above and if
>> you have an idea for something else.
>>
>> Regards
>> Keith
>>
>>
>>
>>
>>
>>
>>
Re: Repository Organization
Posted by Andrea Pescetti <pe...@apache.org>.
marcia wilbur wrote:> I was hoping we would be using gitbox or something
not Github (MS).
Everything under https://github.com/apache/ is actually a Gitbox mirror.
It works the same way for the source code. Some people prefer to push to
Gitbox, some (often including newcomers) to Github. But the two
repositories are synchronized automatically and it doesn't matter which
one you push to.
Regards,
Andrea.
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org
Re: Repository Organization
Posted by F Campos Costero <fj...@gmail.com>.
Marcia - I finished a first pass through Taming, just making notes on
errors or things I would change. I look forward to seeing your suggestions.
Francis
On Wed, Feb 3, 2021 at 7:01 PM marcia wilbur <ai...@well.com> wrote:
> All interesting information.
> I was hoping we would be using gitbox or something not Github (MS).
>
> So, I will finish some more mark up on the Taming and post to this github
> repo - for collaboration purposes.
>
> Probably posting on the 6th - but not looking to do much this week
> (fosdem) and am not available the week of the 8th... So if you have
> questions about the markup, please post in the github or contact me. Will
> have more availability the week of the 15th.
>
> Thanks.
>
>
> ----- Original Message -----
> From: "F Campos Costero" <fj...@gmail.com>
> To: doc@openoffice.apache.org
> Sent: Wednesday, February 3, 2021 11:49:34 AM
> Subject: Re: Repository Organization
>
> I have limited experience with Git, using it only for my own small
> projects, so my opinion should be weighted accordingly. My initial thought
> is to not branch based on releases but to branch on documents. Tagging
> commits as representing a certain AOO release or perhaps as representing a
> certain AOO release with respect to one document would be enough.
>
> Am I right in thinking we would have about 15 documents even if everything
> is brought up to date? The documents that come to mind are one guide per
> application (6), the Taming AOO book, some OS specific short guides, and
> the programming guide. I am not sure whether the developer's guide or the
> building guide are part of the doc team's project.
>
> The work flow I am imagining is to have a branch dedicated to each
> document. When the document is ready to become the latest version, the
> branch is merged into a Main branch that has all of the documents in the
> form in which they appear on the documentation web site. I suppose one
> would update the document-specific branch to the latest version of all the
> other documents just before pushing it to Main, I am not clear on just how
> that would work. None of the public facing documents is ever edited except
> in its own branch. (There might be templates or other administrative
> documents that are handled differently.) Each document-specific branch runs
> on indefinitely since it will always have, in some commit, the
> released version of that document.
>
> Does that make even a little sense?
>
> Francis
>
> On Wed, Feb 3, 2021 at 10:06 AM Dennis Hamilton <or...@msn.com> wrote:
>
> > There is only one project for all of it, so it is not clear how well the
> > handling of multiple guides and other publications can be sequenced and
> > synchronized. Unfortunately, a check-out at this level will bring
> > everything to a contributor's computer. I don't know if there is a
> > finer-grained way to handle this. It would be worth investigating. Most
> > top-level GitHub projects provide multiple (sub-) projects so
> coordination
> > is better. However, github.com/apache/ is that level so such capability
> > is already taken [;<).
> >
> > A subdirectory structure that has a folder for each guide or other
> > publication, and maybe folders on templates and other materials for
> > authors/editors would be helpful. If these are actually (sub-) projects,
> > working is even easier. There could still be subfolders on released,
> draft,
> > or however you want to do that.
> >
> > It is possible to **label** *releases* rather than use branches for that
> > purpose. Also, it is better to branch at the individual document level,
> so
> > maybe the branch name would specify what guide is being worked on in that
> > branch. When a document continues to be applicable to a newer release,
> one
> > could simply tag it for that release as well. There will need to be
> ground
> > rules about this that are clear enough people don't do pushes against the
> > wrong branches, etc. The value is that you don't have to update all the
> > documents for every dot-dot-release and interested parties can look at
> just
> > the Getting Started, or the Writer document or whatever, and know what
> > multiple releases the current one applies to. You may need to have
> > language as part of the substructure also, not just platform, however
> those
> > varieties are to be handled.
> >
> > Sometimes, when the impact of a release is minor, one might one to
> provide
> > a companion supplement to a full guide, also tagged for that release.
> >
> > There are many GitHub projects that can be inspected for how this sort of
> > thing is done. < https://github.com/MicrosoftDocs> is one example
> > although I think the organization can be more thoughtful when focus is on
> > AOO docs. Carl Marcum must know of some approaches related to work he
> has
> > done.
> >
> > If you have the rights, you can also enable Issues, Discussion and even
> > Wiki for the openoffice-docs project. You can then work out matters
> there
> > in a form that is easier and more organized than using docs @ oo.a.o
> > threads as a coordination mechanism.
> >
> > Happy day-after USA Ground Hog Day. We have passed to the other side.
> >
> > - Dennis
> >
> > PS: I still think you need to look at and consult Community Forum folk.
> > There is a significant amount of experience there and it is almost all
> > (power-) user facing.
> >
> >
> > -----Original Message-----
> > From: Keith N. McKenna <ke...@comcast.net>
> > Sent: Wednesday, February 3, 2021 07:20
> > To: doc@openoffice.apache.org
> > Subject: Repository has been created
> >
> > I got word earlier from Carl Marcum that the repository
> > https://github.com/apache/openoffice-docs has been created. It is pretty
> > sparse at the moment as there is only the README.md file from my repo on
> > GitHub.
> >
> > The next step is to define the the branches. Do we want a separate branch
> > for each release of the the software for example 4.1.9, 4.1.10 or just
> for
> > the major.minor, for example 4.1, 4.2 etc.
> >
> > The branch for each release has the potential to create more work in that
> > we could be creating new documentation that has few if any changes to the
> > previous versions.
> >
> > The major.minor branching creates the reverse possibility. We could
> > **not** produce documents when it was warranted.
> >
> > Please reply with any suggestions for either of the schemes above and if
> > you have an idea for something else.
> >
> > Regards
> > Keith
> >
> >
> >
> >
> >
> >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
> For additional commands, e-mail: doc-help@openoffice.apache.org
>
>
Re: Repository Organization
Posted by marcia wilbur <ai...@well.com>.
All interesting information.
I was hoping we would be using gitbox or something not Github (MS).
So, I will finish some more mark up on the Taming and post to this github repo - for collaboration purposes.
Probably posting on the 6th - but not looking to do much this week (fosdem) and am not available the week of the 8th... So if you have questions about the markup, please post in the github or contact me. Will have more availability the week of the 15th.
Thanks.
----- Original Message -----
From: "F Campos Costero" <fj...@gmail.com>
To: doc@openoffice.apache.org
Sent: Wednesday, February 3, 2021 11:49:34 AM
Subject: Re: Repository Organization
I have limited experience with Git, using it only for my own small
projects, so my opinion should be weighted accordingly. My initial thought
is to not branch based on releases but to branch on documents. Tagging
commits as representing a certain AOO release or perhaps as representing a
certain AOO release with respect to one document would be enough.
Am I right in thinking we would have about 15 documents even if everything
is brought up to date? The documents that come to mind are one guide per
application (6), the Taming AOO book, some OS specific short guides, and
the programming guide. I am not sure whether the developer's guide or the
building guide are part of the doc team's project.
The work flow I am imagining is to have a branch dedicated to each
document. When the document is ready to become the latest version, the
branch is merged into a Main branch that has all of the documents in the
form in which they appear on the documentation web site. I suppose one
would update the document-specific branch to the latest version of all the
other documents just before pushing it to Main, I am not clear on just how
that would work. None of the public facing documents is ever edited except
in its own branch. (There might be templates or other administrative
documents that are handled differently.) Each document-specific branch runs
on indefinitely since it will always have, in some commit, the
released version of that document.
Does that make even a little sense?
Francis
On Wed, Feb 3, 2021 at 10:06 AM Dennis Hamilton <or...@msn.com> wrote:
> There is only one project for all of it, so it is not clear how well the
> handling of multiple guides and other publications can be sequenced and
> synchronized. Unfortunately, a check-out at this level will bring
> everything to a contributor's computer. I don't know if there is a
> finer-grained way to handle this. It would be worth investigating. Most
> top-level GitHub projects provide multiple (sub-) projects so coordination
> is better. However, github.com/apache/ is that level so such capability
> is already taken [;<).
>
> A subdirectory structure that has a folder for each guide or other
> publication, and maybe folders on templates and other materials for
> authors/editors would be helpful. If these are actually (sub-) projects,
> working is even easier. There could still be subfolders on released, draft,
> or however you want to do that.
>
> It is possible to **label** *releases* rather than use branches for that
> purpose. Also, it is better to branch at the individual document level, so
> maybe the branch name would specify what guide is being worked on in that
> branch. When a document continues to be applicable to a newer release, one
> could simply tag it for that release as well. There will need to be ground
> rules about this that are clear enough people don't do pushes against the
> wrong branches, etc. The value is that you don't have to update all the
> documents for every dot-dot-release and interested parties can look at just
> the Getting Started, or the Writer document or whatever, and know what
> multiple releases the current one applies to. You may need to have
> language as part of the substructure also, not just platform, however those
> varieties are to be handled.
>
> Sometimes, when the impact of a release is minor, one might one to provide
> a companion supplement to a full guide, also tagged for that release.
>
> There are many GitHub projects that can be inspected for how this sort of
> thing is done. < https://github.com/MicrosoftDocs> is one example
> although I think the organization can be more thoughtful when focus is on
> AOO docs. Carl Marcum must know of some approaches related to work he has
> done.
>
> If you have the rights, you can also enable Issues, Discussion and even
> Wiki for the openoffice-docs project. You can then work out matters there
> in a form that is easier and more organized than using docs @ oo.a.o
> threads as a coordination mechanism.
>
> Happy day-after USA Ground Hog Day. We have passed to the other side.
>
> - Dennis
>
> PS: I still think you need to look at and consult Community Forum folk.
> There is a significant amount of experience there and it is almost all
> (power-) user facing.
>
>
> -----Original Message-----
> From: Keith N. McKenna <ke...@comcast.net>
> Sent: Wednesday, February 3, 2021 07:20
> To: doc@openoffice.apache.org
> Subject: Repository has been created
>
> I got word earlier from Carl Marcum that the repository
> https://github.com/apache/openoffice-docs has been created. It is pretty
> sparse at the moment as there is only the README.md file from my repo on
> GitHub.
>
> The next step is to define the the branches. Do we want a separate branch
> for each release of the the software for example 4.1.9, 4.1.10 or just for
> the major.minor, for example 4.1, 4.2 etc.
>
> The branch for each release has the potential to create more work in that
> we could be creating new documentation that has few if any changes to the
> previous versions.
>
> The major.minor branching creates the reverse possibility. We could
> **not** produce documents when it was warranted.
>
> Please reply with any suggestions for either of the schemes above and if
> you have an idea for something else.
>
> Regards
> Keith
>
>
>
>
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscribe@openoffice.apache.org
For additional commands, e-mail: doc-help@openoffice.apache.org
Re: Repository Organization
Posted by F Campos Costero <fj...@gmail.com>.
I have limited experience with Git, using it only for my own small
projects, so my opinion should be weighted accordingly. My initial thought
is to not branch based on releases but to branch on documents. Tagging
commits as representing a certain AOO release or perhaps as representing a
certain AOO release with respect to one document would be enough.
Am I right in thinking we would have about 15 documents even if everything
is brought up to date? The documents that come to mind are one guide per
application (6), the Taming AOO book, some OS specific short guides, and
the programming guide. I am not sure whether the developer's guide or the
building guide are part of the doc team's project.
The work flow I am imagining is to have a branch dedicated to each
document. When the document is ready to become the latest version, the
branch is merged into a Main branch that has all of the documents in the
form in which they appear on the documentation web site. I suppose one
would update the document-specific branch to the latest version of all the
other documents just before pushing it to Main, I am not clear on just how
that would work. None of the public facing documents is ever edited except
in its own branch. (There might be templates or other administrative
documents that are handled differently.) Each document-specific branch runs
on indefinitely since it will always have, in some commit, the
released version of that document.
Does that make even a little sense?
Francis
On Wed, Feb 3, 2021 at 10:06 AM Dennis Hamilton <or...@msn.com> wrote:
> There is only one project for all of it, so it is not clear how well the
> handling of multiple guides and other publications can be sequenced and
> synchronized. Unfortunately, a check-out at this level will bring
> everything to a contributor's computer. I don't know if there is a
> finer-grained way to handle this. It would be worth investigating. Most
> top-level GitHub projects provide multiple (sub-) projects so coordination
> is better. However, github.com/apache/ is that level so such capability
> is already taken [;<).
>
> A subdirectory structure that has a folder for each guide or other
> publication, and maybe folders on templates and other materials for
> authors/editors would be helpful. If these are actually (sub-) projects,
> working is even easier. There could still be subfolders on released, draft,
> or however you want to do that.
>
> It is possible to **label** *releases* rather than use branches for that
> purpose. Also, it is better to branch at the individual document level, so
> maybe the branch name would specify what guide is being worked on in that
> branch. When a document continues to be applicable to a newer release, one
> could simply tag it for that release as well. There will need to be ground
> rules about this that are clear enough people don't do pushes against the
> wrong branches, etc. The value is that you don't have to update all the
> documents for every dot-dot-release and interested parties can look at just
> the Getting Started, or the Writer document or whatever, and know what
> multiple releases the current one applies to. You may need to have
> language as part of the substructure also, not just platform, however those
> varieties are to be handled.
>
> Sometimes, when the impact of a release is minor, one might one to provide
> a companion supplement to a full guide, also tagged for that release.
>
> There are many GitHub projects that can be inspected for how this sort of
> thing is done. < https://github.com/MicrosoftDocs> is one example
> although I think the organization can be more thoughtful when focus is on
> AOO docs. Carl Marcum must know of some approaches related to work he has
> done.
>
> If you have the rights, you can also enable Issues, Discussion and even
> Wiki for the openoffice-docs project. You can then work out matters there
> in a form that is easier and more organized than using docs @ oo.a.o
> threads as a coordination mechanism.
>
> Happy day-after USA Ground Hog Day. We have passed to the other side.
>
> - Dennis
>
> PS: I still think you need to look at and consult Community Forum folk.
> There is a significant amount of experience there and it is almost all
> (power-) user facing.
>
>
> -----Original Message-----
> From: Keith N. McKenna <ke...@comcast.net>
> Sent: Wednesday, February 3, 2021 07:20
> To: doc@openoffice.apache.org
> Subject: Repository has been created
>
> I got word earlier from Carl Marcum that the repository
> https://github.com/apache/openoffice-docs has been created. It is pretty
> sparse at the moment as there is only the README.md file from my repo on
> GitHub.
>
> The next step is to define the the branches. Do we want a separate branch
> for each release of the the software for example 4.1.9, 4.1.10 or just for
> the major.minor, for example 4.1, 4.2 etc.
>
> The branch for each release has the potential to create more work in that
> we could be creating new documentation that has few if any changes to the
> previous versions.
>
> The major.minor branching creates the reverse possibility. We could
> **not** produce documents when it was warranted.
>
> Please reply with any suggestions for either of the schemes above and if
> you have an idea for something else.
>
> Regards
> Keith
>
>
>
>
>
>
>