github: adding a pull request template #592

bobafetthotmail · 2016-12-06T19:13:19Z

This text is used by GitHub to remind important things to people posting PRs through the GitHub's web interface. See here for more information https://github.com/blog/2111-issue-and-pull-request-templates

Loosely inspired by OpenWRT package feed's own pull request template
https://github.com/openwrt/packages/blob/master/.github/pull_request_template

Signed-off-by: Alberto Bursi alberto.bursi@outlook.it

bobafetthotmail · 2016-12-06T19:15:18Z

feel free to add more requirements to the list in this template.

pepe2k · 2016-12-06T19:20:28Z

This is really great!

I would also add/mention:

preferred approach is to use separate branch for every PR
short tutorial how to rebase and update PR (I see that many people have problems with that when they are asked for changes)

Cheers

miltador · 2016-12-06T19:29:48Z

@pepe2k, your points are good. But I think it would be also nice to have CONTRIBUTING.md file in the root of the project near readme, in which there will be described your points and maybe also other dedicated to contributing info (maybe from LEDE Wiki). GitHub has integration of this file and points user to read it before creating PR.

diizzyy · 2016-12-06T20:02:19Z

I managed to help someone on IRC using this quick and ugly hack...
It's far from optimal but at least this person managed to do a successful pull request :-)
http://paste.ubuntu.com/23472999/

bobafetthotmail · 2016-12-06T20:30:46Z

@miltador the openwrt packages feed has a CONTRIBUTING.md file we can also mostly copy. https://github.com/openwrt/packages/blob/master/CONTRIBUTING.md

Most of other stuff proposed is good for a wiki page, not a short reminder, thanks dizzyyy for that pastebin. Will make a wiki page soon-ish.

wongsyrone · 2016-12-07T00:09:23Z

I think <device-name> should be <arch-name>

EricLuehrsen · 2016-12-07T01:55:47Z

Maybe it could be something more direct and in the form of a check list.

Please check the following before making a pull request:
- Make each commit title "package*: what it fixes or adds"
-- Make commit tittle 50 char max, and line wrap commit body at 72.
-- Confirm your github account is attached to each commit (your personal github icon)
-- Use a unique branch for each pull request so like "package_feature."
- Make the pull request title "package*: summary of combined effect of commits"
-- Describe the problem solved or enhancement in the pull body
-- Describe the compile environment(s) you used in the pull body
-- Describe the test environment(s) you used in the pull body
- Seek additional guidance for developer submissions at: 
-- https://www.lede-project.org/docs/guide-developer/the-source-code#general_source_structure.
-- [github contributing.md]
-- [other]

*package also may be architecture, complete device, or tools component

Thanks for your contribution.
Please remove this message before posting the pull request.

bobafetthotmail · 2016-12-08T12:42:33Z

updated to integrate some of the feedback.

blogic · 2016-12-08T12:51:07Z

.github/pull_request_template

+address
+
+- all commits must be linked to your github account (you see your logo/avatar in front of them), if they aren't 
+linked you probably need to change the local git name or email in your PC to match the one on GitHub.


incorrect, SoB needs to match author field.

blogic · 2016-12-08T12:52:38Z

.github/pull_request_template

+- commit descriptions must describe the problem solved or enhancement in the commit body
+
+- all commits must end with "Signed-off-by: My Name <my@email.address>" where you write your real name and real email 
+address


s/must end with/must contain/

blogic · 2016-12-08T12:53:32Z

.github/pull_request_template

+website)
+
+- commit titles start with "<package name>:" for packages "<device architecture>: " for devices
+- commit titles must state in short form  what was fixed or added


s/titles/subject/

blogic · 2016-12-08T12:54:35Z

.github/pull_request_template

@@ -0,0 +1,23 @@
+Thanks for your contribution to the LEDE project! 
+To help people review your contribution we ask you to follow some rules:
+


s/some/these/

blogic · 2016-12-08T12:54:56Z

.github/pull_request_template

+
+
+- full patch submission rules are here 
+https://www.lede-project.org/docs/guide-developer/the-source-code#general_source_structure


s/rules/guidelines/

bobafetthotmail · 2016-12-08T13:28:50Z

updated.

the email in the Author field for PRs opened through GitHub is the GitHub's "primary email" in the settings, I found out in this PR when you told me to fix mine #471

blogic · 2016-12-08T13:34:36Z

.github/pull_request_template

+address
+
+- the name used in the "Signed-off-by:" line must be the same you write in "Name" field in GitHub settings, and/or 
+see in your PC with "git config user.name"


still incorrect. the author field and SoB need to match.

blogic · 2016-12-08T13:35:34Z

the #471 comment is true if and only if changes are made via the UI. if you push a locally generated tree then the author field is not changed by github.

bobafetthotmail · 2016-12-08T14:29:48Z

updated.

I kept the instructions for fixing Author field as for most newbies it is auto-generated by git (either local or on GitHub) so they have no idea of what you mean by "Author field must match SoB" unless someone explains how to fix it.

blogic · 2016-12-08T14:36:04Z

coming to think of this, the patch you propose does not add a template. it adds an instruction text. a template is, as the name suggests a template that needs to be filled out, like a blank form where you just fill in the fields.

blogic · 2016-12-08T14:37:46Z

.github/pull_request_template

+
+-- if you are editing files and committing through GitHub, you must write your real name in the "Name" field in 
+   GitHub settings and the email used in the "Signed-off-by:" must be your primary github email
+


one of the main problems is that author and SoB do not match. adding an explanation that does not address one of the most common error does not make sense. i am not sure how many more time i need state that it is important to list this here. i have said it 4 times now. but i am happy to repeat myself even more often.

blogic · 2016-12-08T14:38:45Z

adding a commit that explains how to add commits and then having that commit not follow that explanation seems odd. why is there no prefix on the subject line ?

bobafetthotmail · 2016-12-08T14:53:50Z

coming to think of this, the patch you propose does not add a template. it adds an instruction text. a template is, as the name suggests a template that needs to be filled out, like a blank form where you just fill in the fields.

The same was done by Thess for the issue template, see here https://github.com/lede-project/source/blob/master/.github/issue_template
also for OpenWRT package repo it is both a message and a template (link in first message)

Afaik it's common on github to "misuse" the template feature this way as there is no other way to post a message to people making PRs.

adding a commit that explains how to add commits and then having that commit not follow that explanation seems odd. why is there no prefix on the subject line ?

because this is a file for github, not for a package or a device in LEDE, and the commit for the issue template did not have a prefix so I thought it was OK to not have one here too 4f40f22

one of the main problems is that author and SoB do not match. adding an explanation that does not address one of the most common error does not make sense.

What? Author field is auto-generated by git by combining name and email:
On Github's git it uses what you wrote in Name (or your github nickname if no Name is set, like the case with that last guy) and Github's "primary email".
On the committer's local repo it uses user.name and user.email git settings, you can override that with --author=" myname my.email@address", but most guides I've seen tell to set the user.name and user.email globally.

Newbie guides never mention "author field" and there is no such thing in git settings afaik so I have to tell how to set that properly in a document supposed to help newbies.

blogic · 2016-12-08T14:57:37Z

NAK from me until the note is added stating that Author field and SoB line need to match as this is one of the most common errors next to

no prefix
missing description
missing SoB.

bobafetthotmail · 2016-12-08T15:00:52Z

Um, I already wrote in the template:

the Author field the must match the "Signed-off-by:" line:

Did you miss it or is it not clear?

miltador · 2016-12-08T15:02:38Z

coming to think of this, the patch you propose does not add a template. it adds an instruction text. a template is, as the name suggests a template that needs to be filled out, like a blank form where you just fill in the fields.

Agree. This actually can be done in a style of template that user should fill instead of removing the text. As a good example of such, look at this template: https://github.com/serverless/serverless/blob/master/.github/PULL_REQUEST_TEMPLATE.md
It is structured, has points to fill and also the list of checks that can include something like "Added Signed-off-by line" and so on.

EricLuehrsen · 2016-12-08T15:05:00Z

Prefix tools infrastructure with the TOOL.
github: add repo pull request template/message

Or prefix with the package/directory.
LEDE/source: add repo pull request template/message

blogic · 2016-12-08T15:07:25Z

.github/pull_request_template

+- all commits must contain "Signed-off-by: My Name <my@email.address>" where you write your real name and real email 
+  address
+
+- the Author field the must match the "Signed-off-by:" line: 


missed this and looking at it now i see a trailing : that should be removed.

bobafetthotmail · 2016-12-08T15:10:40Z

removed the : now.

blogic · 2016-12-08T15:14:11Z

.github/pull_request_template

+
+
+Please remove this message before posting the pull request.
+


there is a trailing blank line

bobafetthotmail · 2016-12-08T15:19:07Z

removed blank line.

I don't see why that was an issue as this is a plain text file anyway.

bobafetthotmail · 2016-12-14T19:02:47Z

@blogic you said in another of my PRs that dma-buf (a kmod) should have the "kernel:" prefix instead of "package name:". Is that true for all kmod packages too?

blogic · 2016-12-14T19:05:45Z

ideally the prefix should be linux but that is confusing so for this package we use kernel:

git log --oneline will tell you expected prefixes

bobafetthotmail · 2016-12-16T10:50:25Z

please wait, updated the PR too soon.

bobafetthotmail · 2016-12-16T11:01:07Z

ok, done.

bobafetthotmail · 2017-01-11T09:33:00Z

If there are no more comments on this, I think it might make sense merging it.

thagabe · 2017-01-31T00:46:35Z

ping, will this be merged?

bobafetthotmail · 2017-02-05T22:13:24Z

@mkresin you seem to be referencing this commit quite a bit lately, can you merge this or are we waiting for @blogic ?

stefanct · 2017-02-12T23:31:31Z

The build prefix is missing for general build changes that are not targeted at something in toolchain/ AFAICT.

bobafetthotmail · 2017-02-13T00:18:09Z

@stefanct I don't understand what you are saying. Can you explain it better? What you want me to do?

hnyman · 2017-02-13T07:45:39Z

The build prefix is missing for general build changes that are not targeted at something in toolchain/ AFAICT.

I don't understand what you are saying. Can you explain it better? What you want me to do?

He suggests that the prefix examples list should include also "build:" for commits like f938de7 and fe1e362 that target the build logic itself. Also "toolchain:" has been used in some similar cases, e.g. in b2c6672

stefanct · 2017-02-13T07:48:28Z

@bobafetthotmail You are listing some possible prefixes here: c7cfdff#diff-f7162af36e86259e13bfbf7f0fc3eb48R11
I was suggesting that you add some more... what @hnyman said while I was typing ;)
However, toolchain: and build: seem to be distinct to me (there are build files outside of toolchain/.

bobafetthotmail · 2017-02-14T15:09:45Z

ok updated with the "build:" option for non-tool buildsystem changes.
I think a "toolchain" option is unnecessary as there is a "tool name" option already that will catch the tools in /toolchain and stuff in /include or in /scripts (if it is a tool) but this isn't my call anyway.

pepe2k · 2017-03-03T11:31:08Z

Hello @bobafetthotmail,

I would like to move on with this one.
I spoke with @mkresin about the idea of having GitHub PR template inside the repository and few things came out:

we agreed that we need this guideline for submitters, but more like a general submission guideline, not only for GitHub PR
any kind of change in this template text would require a separate commit which we would like to avoid (next point explains why)
we don't keep documentation with sources anymore, so the best place for this would be Wiki (atm, docs/guide-developer/ looks like a good candidate for it, but feel free to suggest something else)
we both think that it should be somehow highlighted and easily available in Wiki menu (side navigation), not "hidden" like the "Submitting Patches" section now
when this will be available in Wiki, we can rework this template and instead of whole guideline text, include only short information and link to the Wiki so that in case of any changes in guideline, we won't need to make changes in code repository

Cheers,
Piotr

bobafetthotmail · 2017-03-03T16:02:43Z

Hm, ok for me. Will migrate bulk of the submission requirements to the wiki and make the required changes in a few days.

bobafetthotmail · 2017-03-05T20:49:43Z

Updated, the wiki article is here https://lede-project.org/docs/guide-developer/contribution (it is accessible from "Contributor's Guide" link on the sidebar on the left)

mkresin · 2017-03-05T21:19:41Z

Excellent work so far.

Any opinions on renaming:

"contributers guide" to "Submitting patches"
"Bug reports" to "Reporting bugs"

IMHO it more descriptive and might help people to find what they are looking for.

EricLuehrsen · 2017-03-05T21:38:03Z

I would like to see a short form underneath like OpenWrt packages, but this has been run to long. Lets just merge this simple piece of literature as is now and be done with it.

bobafetthotmail · 2017-03-05T23:34:04Z

changed the titles on wiki as suggested. (the page link does not change)

pepe2k · 2017-03-06T08:05:06Z

@bobafetthotmail thank you for work on this!

One thing:

redable -> readable (typo?)

Also, it's probably not related to the PR that much, but I will just drop it here.

I have some problem with the Wiki left navigation menu: when I'm in Submitting patches section, the Documentation menu is expanded. Is it some kind of bug/mistake in the menu/pages hierarchy? This is how it looks now:

Cheers,
Piotr

This text is used by GitHub to remind important things to people sending PRs through the GitHub's web interface. See here for more information https://github.com/blog/2111-issue-and-pull-request-templates It links to the wiki page about submission rules. Signed-off-by: Alberto Bursi <alberto.bursi@outlook.it>

bobafetthotmail · 2017-03-06T18:40:27Z

redable -> readable (typo?)

Sigh, respinned the patch again, thanks.

I have some problem with the Wiki left navigation menu:

That's because the page is (was) technically in Developer Guide "namespace thing" in the wiki, see the (old) URL?
https://lede-project.org/docs/guide-developer/contribution
So the wiki expands that menu like when you are in any other article placed under quickstart, user guide or developer guide.

Since I had to fix that typo anyway, I also moved the page to root wiki "namespace" (and changed the link accordingly) so it won't open the menu like that.

pepe2k · 2017-03-06T20:01:19Z

@mkresin, @blogic, what do you think about thist now?

mkresin · 2017-03-06T20:36:39Z

@pepe2k fine with me. Feel free to merge the PR and hopefully it will save us some work.

pepe2k · 2017-03-08T23:42:25Z

@bobafetthotmail and all others involved in work on this, thank you! I have merged this into my staging tree, with tiny change in commit subject.

bobafetthotmail mentioned this pull request Dec 6, 2016

dnsmasq: fix splitting hostid for DHCPv6 static leases #589

Closed

blogic reviewed Dec 8, 2016

View reviewed changes

.github/pull_request_template Outdated

Please remove this message before posting the pull request.

Copy link

Contributor

blogic Dec 8, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there is a trailing blank line

bobafetthotmail changed the title ~~github: adding a github pull request template~~ github: adding a pull request template Dec 16, 2016

This was referenced Feb 14, 2017

ar71xx: WNDR4300: enlarge flash storage space #827

Closed

added support for Kimax U-25AWF #826

Closed

pepe2k self-assigned this Mar 8, 2017

pepe2k closed this Mar 8, 2017

bobafetthotmail deleted the patch-7 branch May 2, 2017 10:02

		@@ -0,0 +1,23 @@
		Thanks for your contribution to the LEDE project!
		To help people review your contribution we ask you to follow some rules:



		- full patch submission rules are here
		https://www.lede-project.org/docs/guide-developer/the-source-code#general_source_structure


		-- if you are editing files and committing through GitHub, you must write your real name in the "Name" field in
		GitHub settings and the email used in the "Signed-off-by:" must be your primary github email

Uh oh!

github: adding a pull request template #592

github: adding a pull request template #592

Uh oh!

Conversation

bobafetthotmail commented Dec 6, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bobafetthotmail commented Dec 6, 2016

Uh oh!

pepe2k commented Dec 6, 2016

Uh oh!

miltador commented Dec 6, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

diizzyy commented Dec 6, 2016

Uh oh!

bobafetthotmail commented Dec 6, 2016

Uh oh!

wongsyrone commented Dec 7, 2016

Uh oh!

EricLuehrsen commented Dec 7, 2016

Uh oh!

bobafetthotmail commented Dec 8, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

blogic Dec 8, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bobafetthotmail commented Dec 8, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

blogic commented Dec 8, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bobafetthotmail commented Dec 8, 2016

Uh oh!

blogic commented Dec 8, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

blogic commented Dec 8, 2016

Uh oh!

bobafetthotmail commented Dec 8, 2016

Uh oh!

blogic commented Dec 8, 2016

Uh oh!

bobafetthotmail commented Dec 8, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

miltador commented Dec 8, 2016

Uh oh!

EricLuehrsen commented Dec 8, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bobafetthotmail commented Dec 8, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bobafetthotmail commented Dec 8, 2016

Uh oh!

bobafetthotmail commented Dec 14, 2016

Uh oh!

blogic commented Dec 14, 2016

Uh oh!

bobafetthotmail commented Dec 16, 2016

Uh oh!

bobafetthotmail commented Dec 16, 2016

Uh oh!

bobafetthotmail commented Dec 6, 2016 •

edited

Loading

miltador commented Dec 6, 2016 •

edited

Loading

blogic Dec 8, 2016 •

edited

Loading

blogic commented Dec 8, 2016 •

edited

Loading

bobafetthotmail commented Dec 8, 2016 •

edited

Loading

EricLuehrsen commented Dec 8, 2016 •

edited

Loading

bobafetthotmail commented Feb 13, 2017 •

edited

Loading

bobafetthotmail commented Feb 14, 2017 •

edited

Loading

mkresin commented Mar 5, 2017 •

edited

Loading

EricLuehrsen commented Mar 5, 2017 •

edited

Loading

bobafetthotmail commented Mar 5, 2017 •

edited

Loading

pepe2k commented Mar 8, 2017 •

edited

Loading