[TYPO3-core] Workflow for changing documentation

[Markus Klein]

Hi!

Sounds good.
At least we should try it out. We can go back to the "old" system anytime if we think we have to.

One question: How do we enforce "proper" commit messages? Or do we accept rather unstructured commit messages then?

Kind regards
Markus

------------------------------------------------------------
Markus Klein
TYPO3 CMS Active Contributors Team Member


> -----Original Message-----
> From: typo3-team-core-bounces at lists.typo3.org [mailto:typo3-team-core-
> bounces at lists.typo3.org] On Behalf Of Xavier Perseguers
> Sent: Monday, May 05, 2014 9:12 AM
> To: typo3-team-core at lists.typo3.org
> Subject: [TYPO3-core] Workflow for changing documentation
> 
> Hi,
> 
> Starting a thread in this list instead of the standard documentation list to
> gather more feedback on an idea floating in the air since many months.
> 
> tl;dr
> -----
> 
> - We should move official manuals to Github in order to simplify the
> contribution workflow
> - Let's discuss that, pros and cons
> 
> 
> Background
> ----------
> 
> - Updating the official manuals/guides/... (TSref, Core API, Beginner Guide,
> ...) requires:
> 
> 	- Spotting a problem by reading
> 	- Filling a ticket on Forge
> 	- Cloning a Git repository (one has to find which one)
> 	- Finding the place in the documentation, fixing/enhancing it
> 	- (Damn!) Configuring Git to contribute to TYPO3
> 	- Pushing to Gerrit
> 	- Not speaking about amending patch after comments are made
> 
> For Active Contributors and other "power users", this is still quite some work.
> I experienced it myself a few weeks ago where I was tempted to simply
> "forget about it" since I would have loved simply clone and push a nobrainer
> without even a ticket.
> 
> 
> Fact
> ----
> 
> - Gerrit is great for our our codebase but much too complicated for
> newcomers which could however be exactly targeted at easily providing
> feedback on our doc to enhance it
> 
> - GitHub's (Bitbucket's / Gitlab's / ...) pull request workflow would be much
> easier to use
> 
> - Git unlike SVN is fully decentralized, meaning we do not have to fear
> anything using another platform to "host" the code since
> 
> 	- Everyone having a clone has the full history
> 	- 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
> 	- 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
> 
> 
> Proposal
> --------
> 
> - Move every official documentation (we may start with 3-4 to start
> with) to Github
> - Remove the requirement for a ticket on Forge when it comes to day-to-day
> change but *keep it* when it comes to documenting some change in the
> Core API (e.g., new feature)
> 
> 
> Rationale
> ---------
> 
> - Let's take an extension of mine, namely "sphinx" that is already mirrored to
> Github (discovered that recently):
> 
> https://github.com/TYPO3-extensions/sphinx/
> 
> tree/master/Documentation/Introduction
> 
> Say someone wants to update the introduction chapter, it's just a matter of
> browsing to https://github.com/TYPO3-
> extensions/sphinx/tree/master/Documentation/Introduction
> and clicking on "Index.rst"
> 
> which redirects to
> https://github.com/TYPO3-
> extensions/sphinx/blob/master/Documentation/Introduction/Index.rst
> 
> >From there one can see the chapter in her browser rendered as HTML
> (cool) and sees a "Edit" button which will automatically fork the repository.
> From there, you /may/ edit the file and create a pull request without ever
> leaving your browser.
> 
> => The whole workflow is straightforward for everyone, including people
> having little to no clue about Git.
> 
> => The edit link is like that:
> https://github.com/TYPO3-
> extensions/sphinx/edit/master/Documentation/Introduction/Index.rst
> meaning we could relatively easily directly link to it from any page on
> docs.typo3.org, as many other projects already do, with a big button similar
> to "Enhance me on Github"
> 
> 
> Other ideas
> -----------
> 
> I would have a few other (I guess cool) ideas about this process but let's
> defer that to later :)
> 
> 
> --
> Xavier Perseguers
> TYPO3 CMS Team Member
> 
> TYPO3 .... inspiring people to share!
> Get involved: http://typo3.org
> 
> _______________________________________________
> Before posting to this list, please have a look to the posting rules on the
> following websites:
> 
> http://typo3.org/teams/core/core-mailinglist-rules/
> http://typo3.org/development/bug-fixing/diff-and-patch/
> _______________________________________________
> TYPO3-team-core mailing list
> TYPO3-team-core at lists.typo3.org
> http://lists.typo3.org/cgi-bin/mailman/listinfo/typo3-team-core