D24068: docs: add contributing guide

[David Edmundson]

davidedmundson added a comment.


  > Since there is no other one at the moment I don't see the need to ask again
  
  You could at least follow up the replies. It was even met with a positive 
response, with some effort this could easily become a thing.
  
  It's a completely different story to say kscreen would become an early 
adopter of an agreed upon new standard we're adopting generically to saying 
we're going to be a special unique snowflake on one tiny subpart of a bigger 
project.
  
  David F also had a really good comment about the "testing done" section, 
that's worth folding into the example.

REPOSITORY
  R104 KScreen

REVISION DETAIL
  https://phabricator.kde.org/D24068

To: romangg, #plasma
Cc: mart, davidedmundson, yurchor, broulik, ngraham, plasma-devel, LeGast00n, 
The-Feren-OS-Dev, jraleigh, fbampaloukas, GB_2, ragreen, ZrenBot, alexeymin, 
himcesjf, lesliezhai, ali-mohamed, jensreuterberg, abetts, sebas, apol, 
ahiemstra

D24068: docs: add contributing guide

[Roman Gilg]

This revision was not accepted when it landed; it landed in state "Needs 
Review".
This revision was automatically updated to reflect the committed changes.
Closed by commit R104:50cf930ec824: docs: add contributing guide (authored by 
romangg).

CHANGED PRIOR TO COMMIT
  https://phabricator.kde.org/D24068?vs=69020=69605#toc

REPOSITORY
  R104 KScreen

CHANGES SINCE LAST UPDATE
  https://phabricator.kde.org/D24068?vs=69020=69605

REVISION DETAIL
  https://phabricator.kde.org/D24068

AFFECTED FILES
  CONTRIBUTING.md
  README.md

To: romangg, #plasma
Cc: mart, davidedmundson, yurchor, broulik, ngraham, plasma-devel, LeGast00n, 
The-Feren-OS-Dev, jraleigh, fbampaloukas, GB_2, ragreen, ZrenBot, alexeymin, 
himcesjf, lesliezhai, ali-mohamed, jensreuterberg, abetts, sebas, apol, 
ahiemstra

D24068: docs: add contributing guide

[Roman Gilg]

romangg added a comment.


  In D24068#558809 , @mart wrote:
  
  > Overall most of those are sensible policies (and would really make sense 
globally in plasma, rather than a specific subproject)
  >  I feel the Conventional Commit policy to rise the barrier of entry a tad 
too much tough (and not sure i would really want it in the resto of plasma)
  
  
  My plan is for new contributors to just edit their Phabricator revision title 
myself such that the conventional commit policy is respected in this regard. In 
general I tried to stay as close as possible to the conventional commit policy 
just so we can talk to them in the future without being a fork. Also I think 
it's easier to relax conditions later on than to introduce stricter ones.
  
  > i think something along those lines would really make sense  globally in 
plasma, having different sub projects having different policies i feel it may 
be confusing to the new contributor... tough, your call, just a personal 
feeling :)
  
  Sue, we should avoid different policies. KScreen/libkscreen are kind of 
isolated on what they do so I think we can go ahead try the policy and either 
scrap it later if it's not working well or discuss after analyzing the 
usefulness in KScreen/libkscreen in which form we want to expand its usage.

REPOSITORY
  R104 KScreen

REVISION DETAIL
  https://phabricator.kde.org/D24068

To: romangg, #plasma
Cc: mart, davidedmundson, yurchor, broulik, ngraham, plasma-devel, LeGast00n, 
The-Feren-OS-Dev, jraleigh, fbampaloukas, GB_2, ragreen, ZrenBot, alexeymin, 
himcesjf, lesliezhai, ali-mohamed, jensreuterberg, abetts, sebas, apol, 
ahiemstra

D24068: docs: add contributing guide

[Marco Martin]

mart added a comment.


  Overall most of those are sensible policies (and would really make sense 
globally in plasma, rather than a specific subproject)
  I feel the Conventional Commit policy to rise the barrier of entry a tad too 
much tough (and not sure i would really want it in the resto of plasma)
  
  i think something along those lines would really make sense  globally in 
plasma, having different sub projects having different policies i feel it may 
be confusing to the new contributor... tough, your call, just a personal 
feeling :)

REPOSITORY
  R104 KScreen

REVISION DETAIL
  https://phabricator.kde.org/D24068

To: romangg, #plasma
Cc: mart, davidedmundson, yurchor, broulik, ngraham, plasma-devel, LeGast00n, 
The-Feren-OS-Dev, jraleigh, fbampaloukas, GB_2, ragreen, ZrenBot, alexeymin, 
himcesjf, lesliezhai, ali-mohamed, jensreuterberg, abetts, sebas, apol, 
ahiemstra

D24068: docs: add contributing guide

[Roman Gilg]

romangg added a comment.


  In D24068#558466 , @davidedmundson 
wrote:
  
  > README is really good.
  >
  > Did you email kde-devel about this commit policy? I thought you did, but I 
can't find it. 
  >  As someone who regularly commits across many many repos if every 
maintainer enforced their own thing I would really struggle.
  
  
  Thanks, I have emailed 
 
about the general policy this one is based on. Since there is no other one at 
the moment I don't see the need to ask again. It would be a rather theoretical 
discussion. Should a second one come around we can align them then.

INLINE COMMENTS

> davidedmundson wrote in CONTRIBUTING.md:68
> What's a BREAKING CHANGE in relation to a UI?
> 
> configs breaking and being unusable or just a button having new text?

I understand it only for API or config breaks, not behavioral changes if there 
is a clean migration path and the user just have to learn a new workflow.

Since I felt it to be somewhat vague or maybe not applicable to all our apps I 
made it less formal here and only recommend it as prose in the commit body.

REPOSITORY
  R104 KScreen

REVISION DETAIL
  https://phabricator.kde.org/D24068

To: romangg, #plasma
Cc: davidedmundson, yurchor, broulik, ngraham, plasma-devel, LeGast00n, 
The-Feren-OS-Dev, jraleigh, fbampaloukas, GB_2, ragreen, ZrenBot, alexeymin, 
himcesjf, lesliezhai, ali-mohamed, jensreuterberg, abetts, sebas, apol, 
ahiemstra, mart

D24068: docs: add contributing guide

[David Edmundson]

davidedmundson added a comment.


  README is really good.
  
  Did you email kde-devel about this commit policy? I thought you did, but I 
can't find it. 
  As someone who regularly commits across many many repos if every maintainer 
enforced their own thing I would really struggle.

INLINE COMMENTS

> CONTRIBUTING.md:68
> +[angular-revert]: 
> https://github.com/angular/angular/blob/3cf2005a936bec2058610b0786dd0671dae3d358/CONTRIBUTING.md#revert
> +[angular-subject]: 
> https://github.com/angular/angular/blob/3cf2005a936bec2058610b0786dd0671dae3d358/CONTRIBUTING.md#subject
> +[bugzilla]: https://bugs.kde.org/describecomponents.cgi?product=KScreen

What's a BREAKING CHANGE in relation to a UI?

configs breaking and being unusable or just a button having new text?

REPOSITORY
  R104 KScreen

REVISION DETAIL
  https://phabricator.kde.org/D24068

To: romangg, #plasma
Cc: davidedmundson, yurchor, broulik, ngraham, plasma-devel, LeGast00n, 
The-Feren-OS-Dev, jraleigh, fbampaloukas, GB_2, ragreen, ZrenBot, alexeymin, 
himcesjf, lesliezhai, ali-mohamed, jensreuterberg, abetts, sebas, apol, 
ahiemstra, mart

D24068: docs: add contributing guide

[Roman Gilg]

romangg updated this revision to Diff 69020.
romangg added a comment.


  Fix typo

REPOSITORY
  R104 KScreen

CHANGES SINCE LAST UPDATE
  https://phabricator.kde.org/D24068?vs=68918=69020

BRANCH
  contributing-guide

REVISION DETAIL
  https://phabricator.kde.org/D24068

AFFECTED FILES
  CONTRIBUTING.md
  README.md

To: romangg, #plasma
Cc: yurchor, broulik, ngraham, plasma-devel, LeGast00n, The-Feren-OS-Dev, 
jraleigh, fbampaloukas, GB_2, ragreen, ZrenBot, alexeymin, himcesjf, 
lesliezhai, ali-mohamed, jensreuterberg, abetts, sebas, apol, ahiemstra, mart

D24068: docs: add contributing guide

[Roman Gilg]

romangg updated this revision to Diff 68918.
romangg added a comment.


  Add a minimal readme file

REPOSITORY
  R104 KScreen

CHANGES SINCE LAST UPDATE
  https://phabricator.kde.org/D24068?vs=68917=68918

BRANCH
  contributing-guide

REVISION DETAIL
  https://phabricator.kde.org/D24068

AFFECTED FILES
  CONTRIBUTING.md
  README.md

To: romangg, #plasma
Cc: yurchor, broulik, ngraham, plasma-devel, LeGast00n, The-Feren-OS-Dev, 
jraleigh, fbampaloukas, GB_2, ragreen, ZrenBot, alexeymin, himcesjf, 
lesliezhai, ali-mohamed, jensreuterberg, abetts, sebas, apol, ahiemstra, mart

D24068: docs: add contributing guide

[Roman Gilg]

romangg updated this revision to Diff 68917.
romangg added a comment.


  Remove scopes common and console. Small areas, do not warrant scope on 
themselves. If there is a change to one of them just don't use the optional 
scope.

REPOSITORY
  R104 KScreen

CHANGES SINCE LAST UPDATE
  https://phabricator.kde.org/D24068?vs=68445=68917

BRANCH
  contributing-guide

REVISION DETAIL
  https://phabricator.kde.org/D24068

AFFECTED FILES
  CONTRIBUTING.md

To: romangg, #plasma
Cc: yurchor, broulik, ngraham, plasma-devel, LeGast00n, The-Feren-OS-Dev, 
jraleigh, fbampaloukas, GB_2, ragreen, ZrenBot, alexeymin, himcesjf, 
lesliezhai, ali-mohamed, jensreuterberg, abetts, sebas, apol, ahiemstra, mart

D24068: docs: add contributing guide

[Roman Gilg]

romangg added inline comments.

INLINE COMMENTS

> yurchor wrote in CONTRIBUTING.md:58
> Typo: "communication" (singular) or "happen"

Thanks!

REPOSITORY
  R104 KScreen

REVISION DETAIL
  https://phabricator.kde.org/D24068

To: romangg, #plasma
Cc: yurchor, broulik, ngraham, plasma-devel, LeGast00n, The-Feren-OS-Dev, 
jraleigh, fbampaloukas, GB_2, ragreen, ZrenBot, alexeymin, himcesjf, 
lesliezhai, ali-mohamed, jensreuterberg, abetts, sebas, apol, ahiemstra, mart

D24068: docs: add contributing guide

[Roman Gilg]

romangg updated this revision to Diff 68445.
romangg marked an inline comment as done.
romangg added a comment.


  - Rebase
  - Fix typo

REPOSITORY
  R104 KScreen

CHANGES SINCE LAST UPDATE
  https://phabricator.kde.org/D24068?vs=66437=68445

BRANCH
  contributingGuide

REVISION DETAIL
  https://phabricator.kde.org/D24068

AFFECTED FILES
  CONTRIBUTING.md

To: romangg, #plasma
Cc: yurchor, broulik, ngraham, plasma-devel, LeGast00n, The-Feren-OS-Dev, 
jraleigh, fbampaloukas, GB_2, ragreen, ZrenBot, alexeymin, himcesjf, 
lesliezhai, ali-mohamed, jensreuterberg, abetts, sebas, apol, ahiemstra, mart

D24068: docs: add contributing guide

[Yuri Chornoivan]

yurchor added a comment.


  Thanks in advance for fixing this minor typo.

INLINE COMMENTS

> CONTRIBUTING.md:58
> +## Contact
> +Real-time communications about the project happens on the IRC channel 
> `#plasma` on freenode and the bridged Matrix room `#plasma:kde.org`.
> +

Typo: "communication" (singular) or "happen"

REPOSITORY
  R104 KScreen

REVISION DETAIL
  https://phabricator.kde.org/D24068

To: romangg, #plasma
Cc: yurchor, broulik, ngraham, plasma-devel, LeGast00n, The-Feren-OS-Dev, 
jraleigh, fbampaloukas, GB_2, ragreen, ZrenBot, alexeymin, himcesjf, 
lesliezhai, ali-mohamed, jensreuterberg, abetts, sebas, apol, mart

D24068: docs: add contributing guide

[Roman Gilg]

romangg added a comment.


  In D24068#534383 , @broulik wrote:
  
  > > The CHANGELOG keyword is cumbersome to use because the summary line most 
often already tells sufficiently what the commit is about. So it would only be 
a repetition of what is already written. Besides why should we want to have a 
disparity between changelog and commit log anyway?
  >
  > I use the CHANGELOG tag quite often. The difference being that the summary 
is perhaps something like "Avoid null pointer dereference" with CHANGELOG being 
a more friendly line for the changelog "Fix crash when doing xyz".
  
  
  I went quickly through KScreen, libkscreen, KWin, KWayland, plasma-desktop 
and plasma-workspace repositories to check if you're an outlier or if it is 
more often used than I expected. Results:
  
  | Repo | Commits w. `CHANGELOG` | Last usage | Kai Uwe share |
  | KScreen  | 2  | May 2016   | 0%|
  | libkscreen   | 2  | Sep 2017   | 0%|
  | KWin | 2  | Mar 2017   | 100%  |
  | KWayland | 1  | Oct 2016   | 0%|
  | plasma-desktop   | 26 | Jun 2019   | 92%   |
  | plasma-workspace | 41 | Aug 2019   | 88%   |
  |
  
  So I admire your expertness on using the available tools to their fullest 
potential in contrast to everybody else but the numbers also show that the 
concept hasn't really caught on. I think a more integrated approach in the 
commit workflow with the prefix can improve the changelogs also quite much. 
Maybe this will then also encourage people to use the CHANGELOG keyword more 
often. Since of course with a common prefix it would still be possible to use 
the keyword.

REPOSITORY
  R104 KScreen

REVISION DETAIL
  https://phabricator.kde.org/D24068

To: romangg, #plasma
Cc: broulik, ngraham, plasma-devel, LeGast00n, The-Feren-OS-Dev, jraleigh, 
fbampaloukas, GB_2, ragreen, ZrenBot, alexeymin, himcesjf, lesliezhai, 
ali-mohamed, jensreuterberg, abetts, sebas, apol, mart

D24068: docs: add contributing guide

[Roman Gilg]

romangg updated this revision to Diff 66437.
romangg added a comment.


  - Explain types

REPOSITORY
  R104 KScreen

CHANGES SINCE LAST UPDATE
  https://phabricator.kde.org/D24068?vs=66424=66437

BRANCH
  contributingGuide

REVISION DETAIL
  https://phabricator.kde.org/D24068

AFFECTED FILES
  CONTRIBUTING.md

To: romangg, #plasma
Cc: broulik, ngraham, plasma-devel, LeGast00n, The-Feren-OS-Dev, jraleigh, 
fbampaloukas, GB_2, ragreen, ZrenBot, alexeymin, himcesjf, lesliezhai, 
ali-mohamed, jensreuterberg, abetts, sebas, apol, mart

D24068: docs: add contributing guide

[Kai Uwe Broulik]

broulik added a comment.


  > The CHANGELOG keyword is cumbersome to use because the summary line most 
often already tells sufficiently what the commit is about. So it would only be 
a repetition of what is already written. Besides why should we want to have a 
disparity between changelog and commit log anyway?
  
  I use the CHANGELOG tag quite often. The difference being that the summary is 
perhaps something like "Avoid null pointer dereference" with CHANGELOG being a 
more friendly line for the changelog "Fix crash when doing xyz".

REPOSITORY
  R104 KScreen

REVISION DETAIL
  https://phabricator.kde.org/D24068

To: romangg, #plasma
Cc: broulik, ngraham, plasma-devel, LeGast00n, The-Feren-OS-Dev, jraleigh, 
fbampaloukas, GB_2, ragreen, ZrenBot, alexeymin, himcesjf, lesliezhai, 
ali-mohamed, jensreuterberg, abetts, sebas, apol, mart

D24068: docs: add contributing guide

[Roman Gilg]

romangg added a comment.


  In D24068#534288 , @ngraham wrote:
  
  > In terms of changelogs, you can already use the FEATURE: and CHANGELOG: 
tags in your commit message. That's already there and similarly we're not 
actually using it. Might it make sense to develop better documentation around 
using those throughout all of KDE?
  
  
  I think that the FEATURE and CHANGELOG keywords are not often used is not a 
problem of missing documentation - it is there after all and I linked to it - 
but that they have issues on a conceptual level:
  
  The FEATURE keyword associates a Bugzilla bug with a commit. But often a new 
feature is not implemented because of a Bugzilla feature request but there was 
a Phabricator task for example.
  The CHANGELOG keyword is cumbersome to use because the summary line most 
often already tells sufficiently what the commit is about. So it would only be 
a repetition of what is already written. Besides why should we want to have a 
disparity between changelog and commit log anyway?
  
  In comparison using the prefix allows to reuse the subject, organize a 
changelog in categories and filter out irrelevant commits for example changes 
to autotests. In a standard case information is not repeated unnecessarily: 
most often already now one writes something like "Fix the poor behavior in 
component". Now one writes: "fix(component): improve behavior".
  
  At last the "special keywords" are something only we in KDE use as far as I 
know, but the Conventional Commits specs, respective the Angular guideline, is 
something a lot of other projects use and their adaption shows that it seems to 
work fine at least for them. Also there are sysadmin/ci tools available to make 
use of it.

REPOSITORY
  R104 KScreen

REVISION DETAIL
  https://phabricator.kde.org/D24068

To: romangg, #plasma
Cc: ngraham, plasma-devel, LeGast00n, The-Feren-OS-Dev, jraleigh, fbampaloukas, 
GB_2, ragreen, ZrenBot, himcesjf, lesliezhai, ali-mohamed, jensreuterberg, 
abetts, sebas, apol, mart

D24068: docs: add contributing guide

[Nathaniel Graham]

ngraham added a comment.


  In terms of changelogs, you can already use the FEATURE: and CHANGELOG: tags 
in your commit message. That's already there and similarly we're not actually 
using it. Might it make sense to develop better documentation around using 
those throughout all of KDE?

REPOSITORY
  R104 KScreen

REVISION DETAIL
  https://phabricator.kde.org/D24068

To: romangg, #plasma
Cc: ngraham, plasma-devel, LeGast00n, The-Feren-OS-Dev, jraleigh, fbampaloukas, 
GB_2, ragreen, ZrenBot, himcesjf, lesliezhai, ali-mohamed, jensreuterberg, 
abetts, sebas, apol, mart

D24068: docs: add contributing guide

[Roman Gilg]

romangg added a comment.


  In D24068#534280 , @ngraham wrote:
  
  > Is this Conventional Commits spec something we think we want to use 
elsewhere? I'm sure I can get used to it, but the prefix thing seems kind of 
rigid and I'm wondering what it really adds other than a bunch of process that 
will need to be explained over and over again to each patch submitter.
  
  
  As I would interpret it the `type` is first of course a concise way to tell 
what the commit is about but it is also there to limit a commit to a single 
purpose prompting to keep the commit size limited.
  
  The optional `scope` you can often already see in several KDE projects being 
used what indicates that this is rather a natural thing to do. Currently the 
format is just not in a consistent manner. Often box brackets are used (KWin 
for example) but these lead to problems with certain git tools I heard in the 
past.
  
  Having the prefix also improves creation of changelogs. I wrote a mail about 
the overall idea as something to unify in all of KDE little while ago to the 
mailing lists: 
https://mail.kde.org/pipermail/kde-frameworks-devel/2019-August/091237.html
  So you can see this here as a test run.

REPOSITORY
  R104 KScreen

REVISION DETAIL
  https://phabricator.kde.org/D24068

To: romangg, #plasma
Cc: ngraham, plasma-devel, LeGast00n, The-Feren-OS-Dev, jraleigh, fbampaloukas, 
GB_2, ragreen, ZrenBot, himcesjf, lesliezhai, ali-mohamed, jensreuterberg, 
abetts, sebas, apol, mart

D24068: docs: add contributing guide

[Nathaniel Graham]

ngraham added a comment.


  Is this Conventional Commits spec something we think we want to use 
elsewhere? I'm sure I can get used to it, but the prefix thing seems kind of 
rigid and I'm wondering what it really adds other than a bunch of process that 
will need to be explained over and over again to each patch submitter.

REPOSITORY
  R104 KScreen

REVISION DETAIL
  https://phabricator.kde.org/D24068

To: romangg, #plasma
Cc: ngraham, plasma-devel, LeGast00n, The-Feren-OS-Dev, jraleigh, fbampaloukas, 
GB_2, ragreen, ZrenBot, himcesjf, lesliezhai, ali-mohamed, jensreuterberg, 
abetts, sebas, apol, mart

D24068: docs: add contributing guide

[Roman Gilg]

romangg updated this revision to Diff 66424.
romangg added a comment.


  - Grammar fix

REPOSITORY
  R104 KScreen

CHANGES SINCE LAST UPDATE
  https://phabricator.kde.org/D24068?vs=66422=66424

BRANCH
  contributingGuide

REVISION DETAIL
  https://phabricator.kde.org/D24068

AFFECTED FILES
  CONTRIBUTING.md

To: romangg, #plasma
Cc: plasma-devel, LeGast00n, The-Feren-OS-Dev, jraleigh, fbampaloukas, GB_2, 
ragreen, ZrenBot, himcesjf, lesliezhai, ali-mohamed, jensreuterberg, abetts, 
sebas, apol, mart

D24068: docs: add contributing guide

[Roman Gilg]

romangg updated this revision to Diff 66422.
romangg added a comment.


  - Add period
  - Change or to and

REPOSITORY
  R104 KScreen

CHANGES SINCE LAST UPDATE
  https://phabricator.kde.org/D24068?vs=66421=66422

BRANCH
  contributingGuide

REVISION DETAIL
  https://phabricator.kde.org/D24068

AFFECTED FILES
  CONTRIBUTING.md

To: romangg, #plasma
Cc: plasma-devel, LeGast00n, The-Feren-OS-Dev, jraleigh, fbampaloukas, GB_2, 
ragreen, ZrenBot, himcesjf, lesliezhai, ali-mohamed, jensreuterberg, abetts, 
sebas, apol, mart

D24068: docs: add contributing guide

[Roman Gilg]

romangg created this revision.
romangg added a reviewer: Plasma.
Herald added a project: Plasma.
Herald added a subscriber: plasma-devel.
romangg requested review of this revision.

REVISION SUMMARY
  This adds a document providing information on how to contribute to KScreen.
  
  It includes clarifications about the used coding style and introduces a Commit
  Message Guideline based on the KDE Commit Policy and the Conventional Commits
  specification.

REPOSITORY
  R104 KScreen

BRANCH
  commitPolicy

REVISION DETAIL
  https://phabricator.kde.org/D24068

AFFECTED FILES
  CONTRIBUTING.md

To: romangg, #plasma
Cc: plasma-devel, LeGast00n, The-Feren-OS-Dev, jraleigh, fbampaloukas, GB_2, 
ragreen, ZrenBot, himcesjf, lesliezhai, ali-mohamed, jensreuterberg, abetts, 
sebas, apol, mart