[tbot] [Discussion] Contribution guidelines

[Stefano Babic]

Hi Harald,

On 03/12/18 12:27, Harald Seiler wrote:
> Hi Stefano,
> thanks for your reply!
> 
> On Mon, 2018-12-03 at 12:17 +0100, Stefano Babic wrote:
>> Hi Harald,
>>
>> On 03/12/18 12:01, Harald Seiler wrote:
>>> Hello all!
>>>
>>> With the recent (and very much welcome!!) increase in contribution
>>> to tbot I felt like it might be necessary to write some guidelines.
>>>
>>> They can be found here:
>>>
>>> 	https://github.com/Rahix/tbot/blob/development/CONTRIBUTING.md
>>>
>>> Please give me feedback about them!  Is there anything missing?  Do
>>> you think something should be changed?  Is anything left unclear?
>>>
>>
>> I think you addressed all technical points. I have just small remarks:
>>
>> - Changelog: why do we have to modify the Changelog when we are using
>> git ? git history contains changes and there are tools as "gbp" that
>> creates a changelog from git history.
> 
> This is a specific decision I made.  The changelog serves to be a quick
> and easy way for a downstream user to see what happened since the last
> version and what they need to change in their code so it works with the
> latest version.

Then it is useful only between release x.y.z to release x1.y1.z1.
Updating the changelog for each commit seems to me too much and
increases the noise that it is supposed to be dropped.

It should be part of the release to write a simple changelog with the
most important changes, dropping what it think it is not needed - at his
discretion. But it should not be part of the single committer.

This currently works because there is just one committer - but think
about you have tens of patches and you want just to apply them. All of
them modifies CHANGELOG.md, and it is in git. Each apply does not work
due to conflict in Changelog.MD.

The other aspect is that a committer *should* align Changelog and commit
message, but it is not said that it does correctly and they are in sync
- and this generates further work.

>  As stated in [1], using the commit log introduces noise
> into this log.
>  A downstream user doesn't care much about changes like
> "Updating Documentation" or the like, in my opinion.

A downstream user just reads the changelog in the annotated tag. If he
needs something more, he will check the git history.

>  But I know other
> projects have other philosophies in that regard ...
> 
> [1]: https://keepachangelog.com/en/1.0.0/#log-diffs
> 
>> - you should mention that patches must have a Signed-off-by
>> - you should mention how you want to get the patches, via ML or via
>> github PR. And if you do not want one of them, say explicitely that you
>> won't care if patches are sent somewhere else !
> 
> Good points!
> 
>> - due to trolls, you should remark that contributors are aware of GPLv2
>> and each contributor is not stealing someone's work.
> 
> v3 in tbot's case ;) But yes, also a good point!
> 
>> If you want to take a look, this is SWUpdate's contributing page:
>>
>> http://sbabic.github.io/swupdate/contributing.html
>>

Best regards,
Stefano


-- 
=====================================================================
DENX Software Engineering GmbH,      Managing Director: Wolfgang Denk
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: +49-8142-66989-53 Fax: +49-8142-66989-80 Email: sbabic at denx.de
=====================================================================