[TYPO3-core] Patches requiring documentation

Markus Klein klein.t3 at mfc-linz.at
Mon Oct 14 15:00:51 CEST 2013


Hi!

> 
> François Suter schrieb am 14.10.2013 08:47:
> 
> > It seems that some contributors are not aware of the guidelines
> > regarding Core patches and documentation that we laid out at the
> > T3ACME before T3DD13. It is already documented quite clearly in the wiki:
> >
> > http://wiki.typo3.org/CommitMessage_Format_(Git)#Relationships
> 
> That's true, but this part was added just this morning, so it's not fair to refer
> to this.

I added this because I was told yesterday that this is a new requirement that I didn't know either.

> 
> I for example haven't known about this new rule, maybe it was not clearly
> communicated as an official change of workflow.
> 
> > When a patch has an impact on documentation (typically it introduces a
> > new TS or TSconfig property, or modified an existing one; same for TCA
> > properties), an issue *must* be opened in the relevant manual and
> > referenced in the Core patch's commit message using:
> >
> > Documentation: #xxxxx
> 
> So the issue should be opened during the review phase already? What
> happens if the change is not merged at the end? Should the documentation
> issue state "this is being reviewed currently" or how will you differenciate
> issues that "need to be documented" from the "not yet merged, this is just a
> placeholder"?

I'd says issues for documentation are always placeholders as long as the referenced code-issue is not in state resolved.

> 
> Forgive me if this has been discussed (maybe even "over and over"), just
> curious about the argument (because I thought we had agreed otherwise
> before): Wouldn't it be more efficient to only document what was merged at
> the end? So that the commit message cannot contain a "Documentation:
> #..." line, but *on merge* the issue *has to be created*?

Although this was new to me as well, I actually like the idea of having a doc issue ready before merge is allowed.

> 
> > It is not required to write the actual documentation patch, although
> > you are very welcome to do so. As you know the Documentation Team is
> > severely understaffed, so it helps a lot if we don't have to dig into
> > the source code to understand how a given property works.
> >
> > I'm pretty sure this was already mentioned, but I couldn't find where.
> > Anyway a reminder is always useful ;-)
> 
> Of course. We have documented it here:
> 
> http://forge.typo3.org/projects/typo3v4-core/wiki/CoreDevPolicy

Yet another wiki page. I love this chaos of Wiki Pages. ;-)
We should come to a point in time where we decide which information has to be where.
My personal wish would be to have only the wiki.typo3.org.
The redmine wikis shall only include a link to the wiki.typo3.org page(s).

> 
> And indeed it was documented in a different way than you are requiring
> now. So please fix the "Core Dev Policy" document to your likings so that we
> can refer to that.
> 
> > Thanks in advance for making the documentation work easier and
> > avoiding that changes get undocumented.
> 
> Indeed a great initiative which we all need to take seriously.
> 
> Also if you "stumble" over some feature which still lack documentation, go
> ahead and add an issue for that too. I do that from time to time.
> 
> Kind regards,
> Ernesto
> 


Kind regards
Markus

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






More information about the TYPO3-team-core mailing list