RFC: Update pr and issue templates

Creating Neos & Flow Code
1

The release-notes and change-logs are autocreated from the merged PRs. That is great but we do not mention this in the PR-Template at all and suggest a structure that needs quite some adjustments before beeing a proper release note.

To make our life easier (especially of future release managers) i suggest to adjust the pr template
slighty and to mention explicitly what the texts will be used for. In addition the checklist is amended with some ticks for the reviewers.

Suggestion PR Template:

<!-- 
     Thanks for your contribution, we appreciate it!

     The first section should explain briefly what was changed. 
     Some examples would are always nice to showcase the use. 
     The content will be used in the change-logs and release notes
     and addresses developers working with Neos.

     If there are issues regarding the topic of your PR link 
     them here as `related:` or `resolved`
-->

**Upgrade instructions**  

<!-- 
     Add upgrade instructions for breaking changes. 
     Explain who is affected, what has to be adjusted  
-->    

**Explanations (to be removed after merging)**     

<!-- 
     If your change is not explained fully by the first section you can 
     add more details here to help the reviewers understand the change.
     We have to understand what you did, why you did it and how we can 
     verify it works correctly and does no harm.
-->

**Checklist (to be removed after merging)**

- [ ] Code follows the PSR-2 coding style
- [ ] Tests have been created, run and adjusted as needed
- [ ] The PR is created against the [lowest maintained branch](https://www.neos.io/features/release-roadmap.html)
- [ ] Reviewer - PR Title is brief but complete and starts with `FEATURE|TASK|BUGFIX` 
- [ ] Reviewer - The first section explains the change briefly for change-logs
- [ ] Reviewer - Breaking Changes are marked wit `!!!` and have upgrade-instructions

For issues i suggest to get away from the “always an issue alongside a pr” rule (at least as long as we generate the change logs from prs) and use those for things that cannot be adjusted right away because they need discussion or no solution can be provided yet.

Suggestion for Issue template:

<!--
    Thanks for your contribution, we appreciate it!

    Issues are for keeping track of things that cannot be adjusted immediately. 
    Either because there is no solution yet, the solution will have to wait 
    for a while or the topic needs some discussion beforehand. 

    If you already have a solution you can create a pull request directly.
    
    Please also take the time and try to avoid reporting duplicates by searching
    for existing issues in the issue-list.
-->

### Description

<!-- 
    Please describe the bug or feature briefly. Try to avoid beeing specific about 
    the solution as there may be more options available.
-->

### Steps to Reproduce

<!--
    To understand your problem faster we need a description how the issue can be 
    reproduced. Please be as specific as possible here, this helps us to solving
    issues faster. Issues that cannot be reproduced are hardly ever fixed.
    
    Please include the observed behavior and the expected behavior in your description.
--> 

### Affected Versions

<!--
    If you report a bug add the versions of Flow and Neos that you are using. 
    If you want to be a super-hero, try to find out the oldest supported version 
    affected by the bug you describe. Thanks!
-->
4 Likes
2

i agree that somehing needs to change as its totally not clear what will be part of the log the issue or the pr?
but i think it should be more clear too when to create an issue see Slack
(its about that issues are needed for the project board)

i found myself often making a nice commit with a long message → add the same text to the pr → make an issue with the same text again so this can be pinned… that seems not right.

and other times i made an detailed issue and the pr was just solves: #X as i assumed the issues are part of the log…

3

I love the format of the the PR Template <3

4

I agree that the issue template should be adjusted aswell and that the relation between both should be explained. I still do not really understand why only issues should be on the board as this imho is pure overhead in most cases.

5

Would it be hard to create an action that creates a comment immediately upon opening a new PR thanking the author and posting the checklist so that we don’t have to remove it manually?

6

…and then combine it with GitHub - stilliard/github-task-list-completed: GitHub - Task list completed PR check maybe?

7

Note: i moved the issue template suggestion that was previously here to the top as this makes more sense.

8

Great idea one downside would be that the checklist would not appear in lists and boards then. But avoiding a possible error may be worth that.

Still i would like to adjust the templates now as it would be an improvement and automate stuff later.

1 Like
9

btw: i found that for automating comments GitHub - exercism/pr-commenter-action: The PR Commenter GitHub action posts comments on a PR that can vary depending on which files are being changed in the PR.

1 Like
10

I like this and making the intention of the PR message parts more clear. As a side-note, we might need to adapt BuildEssentials/GitLogCommand.php at master · neos/BuildEssentials · GitHub to actually strip the changed/new sections from the automatically generated changelog/release notes

1 Like
11

Using a visible marker below that the content is not integrated into the release notes automatically is a great idea. Will integrate that into the proposal.

12

Created PRs: