[TYPO3-core] Workflow for changing documentation

[Philipp Gampe]

Hi Xavier,

Xavier Perseguers wrote:

> - Updating the official manuals/guides/... (TSref, Core API, Beginner
> Guide, ...) requires:

Gerrit                                        Github
============================================================================
Spotting a problem                            Spotting a problem
Creating a t3o account                        Creating a github account
Filling a ticket on Forge                     Filling a ticket on Forge
Cloning a Git repository                      Fork a repository
(one has to find which one)                   (right one preselected)

Finding the place in the documentation, fixing/enhancing it (both)

Configuring Git for gerrit (once)             ----
Pushing to Gerrit                             Creating a pull request
Make comments/review                          Make comments/review
Amend and push again                          Edit again (auto-commit)

Merge change                                  Merge change


Not much different. The only real things are configuring the gerrit commit 
message hook and - more important - the online editing of files.
I already proposed a simpler workflow for editing changes, by pushing online 
changes to a web service. Since we have a jobqueue now, this could be 
implemented on the next community tools code sprint.
BTW, is there any documentation of the used tools and all used tools in a 
repository such that one could easily enhance the documentation server?




> - Everyone having a clone has the full history
minus comments and review notes

> - Idea is not to tie us to any external service, just make use of it
> "out-of-the-box" and switch back/further whenever we think it's needed

Switch back is not easy. We would need to edit all contribution 
documentation again. On top of that we need to closely monitor the external 
service to find out of something changes regarding our contribution 
workflow.

> - git.typo3.org may easily read-only mirror any external repository if
> we would feel safer this way, just as
> https://github.com/TYPO3-extensions/ is doing the other way around
Needs to be implemented.

Online editing would make things easier for beginners, but keep in mind that 
they need a github account to do so.

Dropping the requirement for proper commit message has nothing to do with 
gerrit/github.






Ok, taking a test drive with your sphinx extension (using the provided 
link).
* Editing comes up nicely (I am already logged in to github)
* Found the preview page
* Searched the save button (there is none)
* Found the form below, knowing git (!!!) I know what is going on
* I guess a users would have tried to "propose file change" button anyway
  after a while, thus lets continue
* dropped to some technical page, taking about fork, merge, patch and
  pull request
  - not sure what to do
  - lots of technical details around
  - my changes are displayed on the bottom
  - for some reason the same fields are displayed as the step before,
    but with the data pre-filled
  - there is a single green button talking about "send pull request"
  - lets click it
* Page looks almost the same as before
  - Many technical details (I wonder what they can be used for)
  - I can add comments below now
* What to do now? Change send? Anything to do from here?
* I hit close, but I do not think it did what I wanted to do ;)

Of course I purposely tried to play stupid a bit, but you should not assume 
that user finds its way around github. It is still very technical.

https://github.com/TYPO3-extensions/sphinx/pull/1