You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomee.apache.org by David Blevins <da...@gmail.com> on 2018/11/26 20:32:01 UTC
PRs and descriptive subjects
Quick note that emails for PRs should have a description of the work in the subject line. Here are some examples and why:
- bad: This is an email about PR #451
- bad: See PR #451
- bad: Review PR #451
- bad: Help needed in PR #451
With this style you'll get low participation on the thread as the subject is hidden. You yourself will curse these emails in six months or a year in the future when you're looking for that valuable thread you remember, but your search reveals 10 threads all with basically only a number as the subject. You'll either click and read all 10 PRs and email threads, or you'll more likely just give up. Worse, you may read all 10 and not find what you're looking for. Do your future self a favor and help him/her find the valuable discussions.
- ok: Options pertaining to the configuration of Javamail - PR# 451
- ok: Fixing issues on failover of JMS messages - PR# 451
- ok: Documenting deployment of JCA Connectors - PR# 451
These are ok, much better than just a number. Subjects are often truncated. The real "meat" is at the end of the sentence which makes it the first to go. Not a show-stopper, but can make your life hard when searching or scanning.
- best: Javamail configuration options - PR# 451
- best: JMS Failover issues - PR# 451
- best: JCA connector deployment - PR# 451
Here we flip it. The real subject as at the beginning. The verbs and generic nouns like "options" come after. When you can pull it off, huge respect.
--
David Blevins
http://twitter.com/dblevins
http://www.tomitribe.com
Re: PRs and descriptive subjects
Posted by César Hernández Mendoza <ce...@gmail.com>.
+1.
El lun., 26 nov. 2018 a las 14:32, David Blevins (<da...@gmail.com>)
escribió:
> Quick note that emails for PRs should have a description of the work in
> the subject line. Here are some examples and why:
>
> - bad: This is an email about PR #451
> - bad: See PR #451
> - bad: Review PR #451
> - bad: Help needed in PR #451
>
> With this style you'll get low participation on the thread as the subject
> is hidden. You yourself will curse these emails in six months or a year in
> the future when you're looking for that valuable thread you remember, but
> your search reveals 10 threads all with basically only a number as the
> subject. You'll either click and read all 10 PRs and email threads, or
> you'll more likely just give up. Worse, you may read all 10 and not find
> what you're looking for. Do your future self a favor and help him/her find
> the valuable discussions.
>
>
> - ok: Options pertaining to the configuration of Javamail - PR# 451
> - ok: Fixing issues on failover of JMS messages - PR# 451
> - ok: Documenting deployment of JCA Connectors - PR# 451
>
> These are ok, much better than just a number. Subjects are often
> truncated. The real "meat" is at the end of the sentence which makes it
> the first to go. Not a show-stopper, but can make your life hard when
> searching or scanning.
>
> - best: Javamail configuration options - PR# 451
> - best: JMS Failover issues - PR# 451
> - best: JCA connector deployment - PR# 451
>
> Here we flip it. The real subject as at the beginning. The verbs and
> generic nouns like "options" come after. When you can pull it off, huge
> respect.
>
>
> --
> David Blevins
> http://twitter.com/dblevins
> http://www.tomitribe.com
>
>
--
Atentamente:
César Hernández Mendoza.
Re: PRs and descriptive subjects
Posted by Frankie <ka...@gmx.de>.
I have included your tips in the new contribution workflow documentation.
Hope that's ok
--
Sent from: http://tomee-openejb.979440.n4.nabble.com/TomEE-Dev-f982480.html
Re: PRs and descriptive subjects
Posted by Jonathan Gallimore <jo...@gmail.com>.
Good shout. I think they'll need to be closed by their original authors
(unless someone knows a trick I don't...). I'll go and clean mine up.
Jon
On Tue, Nov 27, 2018 at 3:54 PM exabrial12 <ex...@gmail.com> wrote:
> Speaking of, is it possible to go an clean up the old PRs that might not be
> relevant? I hate to see them sitting there, it makes the community look
> abandoned. I can try and close a few this weekend, but there's quite a few
> that need to be reviewed.
>
>
>
> --
> Sent from:
> http://tomee-openejb.979440.n4.nabble.com/TomEE-Dev-f982480.html
>
Re: PRs and descriptive subjects
Posted by exabrial12 <ex...@gmail.com>.
Speaking of, is it possible to go an clean up the old PRs that might not be
relevant? I hate to see them sitting there, it makes the community look
abandoned. I can try and close a few this weekend, but there's quite a few
that need to be reviewed.
--
Sent from: http://tomee-openejb.979440.n4.nabble.com/TomEE-Dev-f982480.html
Re: PRs and descriptive subjects
Posted by Ivan Junckes Filho <iv...@gmail.com>.
Great tips David, thanks!
On Mon, Nov 26, 2018 at 6:32 PM David Blevins <da...@gmail.com>
wrote:
> Quick note that emails for PRs should have a description of the work in
> the subject line. Here are some examples and why:
>
> - bad: This is an email about PR #451
> - bad: See PR #451
> - bad: Review PR #451
> - bad: Help needed in PR #451
>
> With this style you'll get low participation on the thread as the subject
> is hidden. You yourself will curse these emails in six months or a year in
> the future when you're looking for that valuable thread you remember, but
> your search reveals 10 threads all with basically only a number as the
> subject. You'll either click and read all 10 PRs and email threads, or
> you'll more likely just give up. Worse, you may read all 10 and not find
> what you're looking for. Do your future self a favor and help him/her find
> the valuable discussions.
>
>
> - ok: Options pertaining to the configuration of Javamail - PR# 451
> - ok: Fixing issues on failover of JMS messages - PR# 451
> - ok: Documenting deployment of JCA Connectors - PR# 451
>
> These are ok, much better than just a number. Subjects are often
> truncated. The real "meat" is at the end of the sentence which makes it
> the first to go. Not a show-stopper, but can make your life hard when
> searching or scanning.
>
> - best: Javamail configuration options - PR# 451
> - best: JMS Failover issues - PR# 451
> - best: JCA connector deployment - PR# 451
>
> Here we flip it. The real subject as at the beginning. The verbs and
> generic nouns like "options" come after. When you can pull it off, huge
> respect.
>
>
> --
> David Blevins
> http://twitter.com/dblevins
> http://www.tomitribe.com
>
>