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 <orc...@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 <keith.mcke...@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 > > > > > > >
