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 <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 >> >> >> >> >> >> >>
signature.asc
Description: OpenPGP digital signature
