add PULL_REQUEST_TEMPLATE file to the project

[vbence86]

Prelude

Pull Requests are the main channels to administer changes to the project and therefore must be as verbose as possible. To enhance visibility on what changes contributors are planning to introduce we add a basic template for pull requests.

Issue

#790

Solution

Following the guidelines of GitHub, I've added PULL_REQUEST_TEMPLATE.md file to the repository.

Test

None

[jbalsas]

Hey @vbence86, thanks for starting this!

Seeing as this would be the content you'd see when starting a PR from the GitHub interface, I think having both the explanation and example is a bit redundant. People will be forced to remove a lot of unnecessary content. We probably should have one or the other.

I also like these examples with prerequisites and checklist

Finally, one pattern I've seen and I liked was putting these templates inside a .github folder, so its clearly marked as a github meta-file rather than source code.

@zenorocha, what do you think about this? do we have some other template we should use as a starting point? do we want to converge on something?

[jbalsas]

Project name should be AlloyEditor (or liferay/alloy-editor if we want to refer to the github repo).

Possible typo re**q**arded -> re**g**arded

[jbalsas]

Maybe missing to connector? -> history of the issue related **to** this very Pull Request

[vbence86]

@jbalsas Many thanks your suggestions, they are all welcomed. I'm now addressing all your concerns.

Example section

Actually I'd been under the same impression, but I thought I'd leave it there for further considerations, but your remark reassured me that it is indeed redundant.

Typos

They will be fixed now.

Prequisits and Checkboxes

I'm not for nor against this approach. I like the terms and concepts GitHub came up with: Request and Conversation. I think pull request is indeed a request in which a contributor want to add potential value to the project which should be discussed through the conversation channel. I wouldn't use it as another filter that might imply possible delays. Having said that, it might provide benefits for us at some level, but I'd definitely have a more relaxed template as the first step towards a generic and comprehensive strategy.

I've got experience with checkboxes, but I haven't found them useful at any point in time. Especially here where there is a neat CI process in existence that has been working so smoothly. We've got guidelines, linting, automated tests and rigorous peer review. I don't see much advantage of another artificially induced layer of restrictions that might make the whole process less agile. I'd rather we had a more strict template for the ISSUES.

.github folder

I was going to put this into the .github folder as you proposed, but having the README.md and BREAKING_CHANGES.md already placed in the root folder, I've kept this there as well. I'm very happy to relocate it there though.

[jbalsas]

Hey @vbence86

I don't see much advantage of another artificially induced layer of restrictions that might make the whole process less agile. I'd rather we had a more strict template for the ISSUES.

I agree. I'll check #794 first and then we can add here whatever we feel missing after the issue description.

I was going to put this into the .github folder as you proposed, but having the README.md and BREAKING_CHANGES.md already placed in the root folder, I've kept this there as well. I'm very happy to relocate it there though.

Both README.md and BREAKING_CHANGES.md are organic to the repo and the code, whereas these templates are a GitHub-only kind of thing. I say let's move it, no need to concern people with that piece of code :)

[jbalsas]

@Robert-Frampton, mind providing some input for this as well? :)