863443 - Contribution Guidelines not Discoverable

Status: RESOLVED FIXED

(Firefox OS Graveyard :: Gaia, defect)

Description

[Mike Pennisi [:jugglinmike]]

Although expectations around new contributions are well-maintained on the Mozilla Wiki[1], these may not be clear to users who discover Gaia through its GitHub repository. For example the following requirements are undocumented:

- a patch should have a corresponding bug filed in BugZilla
- a patch should contain the associated bug number in its commit message title
- a patch should have the reviewer's name in its commit message

Because the wiki is not referenced in the README.md file, these requirements are not at all discoverable.

[1] https://wiki.mozilla.org/Gaia/Hacking

Comment 1

[Mike Pennisi [:jugglinmike]]

Attachment: Add file for contribution guidelines

As noted in the commit message, GitHub.com will link to this file whenever the web interface is used to open an issue or pull request.

I think it's a good idea to keep this minimal in order to limit duplication (and prevent possible contradictions) with the guidelines hosted on the Mozilla Wiki.

Comment 2

[Mike Pennisi [:jugglinmike]]

In addition, julienw and I discussed the possibility of disabling the "issues" feature on GitHub.com altogether for the following reasons:

1. It is confusing. New developers could not be faulted for assuming that it is the preferred method of filing bugs (while in reality, BugZilla is the preferred tool for tracking this information)

2. Left unmaintained, it is discouraging. New developers may assume that a project with many many open issues on GitHub (over 500 at the time of this writing) does not value the input of most contributors.

Comment 3

[Mike Pennisi [:jugglinmike]]

Finally, the presence of long-standing pull requests tends to suggest that this is the preferred method for submitting and discussing patches. Again, this is not the case, and persisting hundreds of irrelevant open pull requests will have the same negative effects as listed above.

We should consider closing all obsolete pull requests and promoting stricter practices around managing new requests.

Comment 4

[Julien Wajsberg [:julienw] (PTO -> may 13)]

comment 2 and comment 3 should be sent to the mailing lists instead.

You can maybe raise the topic as soon as we land this.

Comment 5

[Julien Wajsberg [:julienw] (PTO -> may 13)]

Comment on attachment 739269 [details] [diff] [review]
Add file for contribution guidelines

Review of attachment 739269 [details] [diff] [review]:
-----------------------------------------------------------------

Thanks, that will be a healthy addition !

::: CONTRIBUTING.md
@@ +1,5 @@
> +# Contributing to Gaia
> +
> +Before submitting a pull request on GitHub, please create a bug report on
> +[BugZilla](https://bugzilla.mozilla.org/) under [Boot2Gecko >
> +Gaia](https://bugzilla.mozilla.org/buglist.cgi?product=Boot2Gecko&component=Gaia&resolution=---).

I think you wanted to use https://bugzilla.mozilla.org/enter_bug.cgi?product=Boot2Gecko&component=Gaia instead ?

You can maybe precise that "you can choose a more specific module if your problem focus on a specific area of Boot2Gecko, eg a specific app".

@@ +4,5 @@
> +[BugZilla](https://bugzilla.mozilla.org/) under [Boot2Gecko >
> +Gaia](https://bugzilla.mozilla.org/buglist.cgi?product=Boot2Gecko&component=Gaia&resolution=---).
> +
> +For more details on contributing to Gaia, please see [the Gaia/Hacking page of
> +the Mozilla Wiki](https://wiki.mozilla.org/Gaia/Hacking).

The correct URL is https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Platform/Gaia/Hacking.

Comment 6

[Mike Pennisi [:jugglinmike]]

Attachment: Add file for contribution guidelines

Comment 7

[Mike Pennisi [:jugglinmike]]

Thanks, Julien. I've made the modifications you suggested, and I will send comment 2 and comment 3 to the Gaia mailing list once this lands.

Comment 8

[Julien Wajsberg [:julienw] (PTO -> may 13)]

Comment on attachment 740764 [details] [diff] [review]
Add file for contribution guidelines

Review of attachment 740764 [details] [diff] [review]:
-----------------------------------------------------------------

sorry about that, I should have given the right name in the first place.

::: CONTRIBUTING.md
@@ +2,5 @@
> +
> +Before submitting a pull request on GitHub, please create a bug report on
> +[BugZilla](https://bugzilla.mozilla.org/) under [Boot2Gecko >
> +Gaia](https://bugzilla.mozilla.org/enter_bug.cgi?product=Boot2Gecko&component=Gaia).
> +You can choose a more specific module if your problem pertains to a single

ok, I think the blessed word is "component" here instead of "module", sorry about that...

@@ +3,5 @@
> +Before submitting a pull request on GitHub, please create a bug report on
> +[BugZilla](https://bugzilla.mozilla.org/) under [Boot2Gecko >
> +Gaia](https://bugzilla.mozilla.org/enter_bug.cgi?product=Boot2Gecko&component=Gaia).
> +You can choose a more specific module if your problem pertains to a single
> +component of Boot2Gecko (e.g. a specific application).

and then maybe chose another word here (to avoid repetition) but I'll let you choose.

Comment 9

[Mike Pennisi [:jugglinmike]]

Attachment: Add file for contribution guidelines (v3)

This version corrects errors in naming conventions (as described in comment 8).

Comment 10

[Mike Pennisi [:jugglinmike]]

Attachment: Add file for contribution guidelines (v3)

I erroneously re-submitted an old patch. Sorry about that!

Comment 11

[Mike Pennisi [:jugglinmike]]

Attachment: Add file for contribution guidelines (v4)

Re-submitting once again. Not sure what's going on here (possibly a caching issue). Sorry for the noise!

Comment 12

[Julien Wajsberg [:julienw] (PTO -> may 13)]

Comment on attachment 740900 [details] [diff] [review]
Add file for contribution guidelines (v4)

Review of attachment 740900 [details] [diff] [review]:
-----------------------------------------------------------------

r=me

will merge, thanks !

Comment 13

[Julien Wajsberg [:julienw] (PTO -> may 13)]

master: 0589e45f69b0b8e96193442e71f67fa17623039c

Comment 14

[Mike Pennisi [:jugglinmike]]

I've been in contact with GitHub support regarding what I consider to be a bug in the treatment of the `contributing.md` file*. I am going to wait until the resolution of that work before raising the concerns in comment 2 and comment 3 on the mailing list (in order to avoid confusion).

* - Strangely, GitHub only displays a message about the project's `contributing.md` file if it exists in the HEAD of the user's fork. In this case, the message will reference the `contributing.md` file in the user's fork--*not* the version in the repository for which they are issuing a pull request. This means that if their `master` branch is behind Mozilla's, the message may be out of date (or may not be rendered at all).

Comment 15

[Julien Wajsberg [:julienw] (PTO -> may 13)]

thanks for investigating this, this is also imho a bug on their end.

Comment 16

[Mike Pennisi [:jugglinmike]]

I haven't heard back from GitHub.com's support staff, but it appears that they've fixed this behavior. I will compose an e-mail to the Gaia mailing list based on comment 2 and comment 3

Comment 17

[Julien Wajsberg [:julienw] (PTO -> may 13)]

Yep, it's still not displayed, but at least there is a link...