[TYPO3-core] Patches requiring documentation

[Ernesto Baschny [cron IT]]

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 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"?

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*?

> 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

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