Getting "approval" to go ahead
I haven’t really worked on an open source project before.
It wouldn’t make sense to come up with an idea, write some code, submit it and have it rejected because it’s not OK with the project owners and doesn’t fit with project goals.
So at what point do I know that if I write some code that the concept is solid and will be integrated into the project assuming the quality is there? Do I need explicit approval from someone like Barry or Stephen?
Also, is there a development workflow checklist or something I can use to ensure that I am meeting all requirements for submitted code?
thanks
as
Hi Andrew,
For starters, make sure you check https://pythonhosted.org/mailman/src/mailman/docs/STYLEGUIDE.html and https://google-styleguide.googlecode.com/svn/trunk/pyguide.html.
Cheers, Ana
On Tue, Mar 24, 2015 at 5:38 AM, Andrew Stuart < andrew.stuart@supercoders.com.au> wrote:
I haven’t really worked on an open source project before.
It wouldn’t make sense to come up with an idea, write some code, submit it and have it rejected because it’s not OK with the project owners and doesn’t fit with project goals.
So at what point do I know that if I write some code that the concept is solid and will be integrated into the project assuming the quality is there? Do I need explicit approval from someone like Barry or Stephen?
Also, is there a development workflow checklist or something I can use to ensure that I am meeting all requirements for submitted code?
thanks
as
Mailman-Developers mailing list Mailman-Developers@python.org https://mail.python.org/mailman/listinfo/mailman-developers Mailman FAQ: http://wiki.list.org/x/AgA3 Searchable Archives: http://www.mail-archive.com/mailman-developers%40python.org/ Unsubscribe: https://mail.python.org/mailman/options/mailman-developers/anabee.emacs%40gm...
Security Policy: http://wiki.list.org/x/QIA9
On 2015-03-23 8:38 PM, Andrew Stuart wrote:
I haven’t really worked on an open source project before.
It wouldn’t make sense to come up with an idea, write some code, submit it and have it rejected because it’s not OK with the project owners and doesn’t fit with project goals.
So at what point do I know that if I write some code that the concept is solid and will be integrated into the project assuming the quality is there? Do I need explicit approval from someone like Barry or Stephen?
Also, is there a development workflow checklist or something I can use to ensure that I am meeting all requirements for submitted code?
Sadly, we aren't quite formal enough to have a procedure beyond "post your plan to the mailing list and make sure no one (particularly not Barry!) tells you 'no'".
Unfortunately, it is true that the lack of process has led people to put a lot of work into stuff that never got merged.
If you'd feel more comfy with a bit more of a process, you might consider doing up something like a pep https://www.python.org/dev/peps/pep-0001/
For core stuff you particularly want Barry's blessing, for Hyperkitty it's Aurelian, for Postorius it's Florian or me.
Terri
Thanks Terri,
Unfortunately, it is true that the lack of process has led people to put a lot of work into stuff that never got merged. I’m mainly just trying to avoid this - writing stuff that doesn’t get merged.
I figure step one is to get a quick nod from one of the architects/project leads, so if my code is rejected its not because the idea is not compatible with the project goals.
I’m less after a formal process. Looking for an informal “sounds good, go ahead”, or “that’s not going to fit with the project goals, maybe change it this way or that or ditch the idea altogether”.
The question is, who do I ask for confirmation that the idea is solid and will be merged assuming all requirements are met for code quality/testing/documentation?
thanks
as
On 24 Mar 2015, at 4:27 pm, Terri Oda <terri@toybox.ca> wrote:
On 2015-03-23 8:38 PM, Andrew Stuart wrote:
I haven’t really worked on an open source project before.
It wouldn’t make sense to come up with an idea, write some code, submit it and have it rejected because it’s not OK with the project owners and doesn’t fit with project goals.
So at what point do I know that if I write some code that the concept is solid and will be integrated into the project assuming the quality is there? Do I need explicit approval from someone like Barry or Stephen?
Also, is there a development workflow checklist or something I can use to ensure that I am meeting all requirements for submitted code?
Sadly, we aren't quite formal enough to have a procedure beyond "post your plan to the mailing list and make sure no one (particularly not Barry!) tells you 'no'".
Unfortunately, it is true that the lack of process has led people to put a lot of work into stuff that never got merged.
If you'd feel more comfy with a bit more of a process, you might consider doing up something like a pep https://www.python.org/dev/peps/pep-0001/
For core stuff you particularly want Barry's blessing, for Hyperkitty it's Aurelian, for Postorius it's Florian or me.
Terri
On 2015-03-23 10:38 PM, Andrew Stuart wrote:
The question is, who do I ask for confirmation that the idea is solid and will be merged assuming all requirements are met for code quality/testing/documentation?
For core stuff you particularly want Barry's blessing, for Hyperkitty it's Aurelian, for Postorius it's Florian or me.
Answering the question by quoting the part where I already answered the question. ;)
Terri
On Mar 24, 2015, at 02:38 PM, Andrew Stuart wrote:
I haven’t really worked on an open source project before.
You're fitting right in though! :)
It wouldn’t make sense to come up with an idea, write some code, submit it and have it rejected because it’s not OK with the project owners and doesn’t fit with project goals.
I think Terri summarized things well, so I'll just add a few things as it relates to core.
A Launchpad bug is always a good place to augment a mailing list discussion. You can hang branches and merge proposals off of bugs, and we can have a conversation about the details of either the idea (on the bug) or the implementation (on the merge proposal).
Always tag the bug 'mailman3' for Mailman 3. It helps me find them better. I can then triage the bug, assign it to a milestone, raise or lower the priority, etc.
Let's say you have a crazy idea for a new feature. Bring it up here and let's start the discussion going. If it seems like a good idea, and aligned with the project goals, create a bug and start hacking. Attach your branch to the bug. When you think it's ready for review, create a merge proposal against trunk (i.e. lp:mailman).
Some things that I look for right away: conformance to PEP 8 and our own style guide. I don't expect branches to be 100% conformant to style, but I think it's not hard to get close if you follow the guides and try to look like existing code.
Doctests that explain the feature and unit tests that cover the new code. Doctests are documentation first, so are expected to explain good-path behavior and usage. Unit tests cover corner cases, error conditions, etc. Tests should be included at each appropriate level (e.g. model, REST). The tests should fail without your "fix" and pass with them applied. There should be no regressions in the rest of the test suite.
Keep feature and bug branches small if possible, and concise, such that they only implement the feature your working on or fix the reported bug. A little bit of extraneous stuff might be okay if it improves readability, but don't go overboard.
That's probably the basics. I promise I will try to be kind, fair, and thankful for your contributions, though I might be rather strict in my opinions. If you really disagree, let's discuss respectfully!
Cheers, -Barry
Barry Warsaw writes:
Keep feature and bug branches small if possible, and concise, such that they only implement the feature your working on or fix the reported bug. A little bit of extraneous stuff might be okay if it improves readability, but don't go overboard.
I'd like to gloss this a bit.
(1) Suppose you change a small function whose formatting is not PEP 8 conformant (or otherwise so ugly you can't help fixing it -- of course, check "blame" first, if Barry committed those lines, have your eyes checked instead :-). I would (1) fix the problem in the current style, commit, and then (2) reformat the function to PEP 8, and give that a separate commit. If the number of lines that would *not* be in the diff at all if you didn't mess with style is greater than the number of lines in the diff from step (1), don't do step (2) without checking with the project leads.
(2) Documentation and test changes implied by your code changes should go in the same branch. In other projects I usually commit docstring changes with the code change, and use two more commits, one for standalone docs and one for unit tests.
(3) Unrelated documentation changes (eg, a typo you notice in another function's docstring, or you want to add a docstring to an undocumented function that you had to study) should go in a separate *branch*. I usually have a branch just to collect these small improvements, and push them (or submit a merge request, depending on the project workflow) all at once.
These practices are noticably tedious for the committer, but I find they greatly improve the usefulness of commit logs and the readability of diffs. It's not officially in the Zen of Python, but widely acknowledged, that Python should be written with the assumption that the code will be read many thousand times more often than it's written.
On Mar 25, 2015, at 01:02 PM, Stephen J. Turnbull wrote:
(1) Suppose you change a small function whose formatting is not PEP 8 conformant (or otherwise so ugly you can't help fixing it -- of course, check "blame" first, if Barry committed those lines, have your eyes checked instead :-). I would (1) fix the problem in the current style, commit, and then (2) reformat the function to PEP 8, and give that a separate commit. If the number of lines that would *not* be in the diff at all if you didn't mess with style is greater than the number of lines in the diff from step (1), don't do step (2) without checking with the project leads.
+1; of course, I'm happy to look at purely style fixing branches, again if they're small, concise, and manageable. If I can't tell that only style was changed (i.e. no features or bug fixes snuck in) then I'd probably reject it.
My general approach for style nits is:
If they're pervasive (e.g. lots of too-long lines), I'll move the mp to Needs Fixing and ask you to repair them.
If they're fairly minor or rare, I'll comment about them in the mp and fix them up when I merge. I don't want to be so nitpicky as to reject a good branch just for some minor style issues, but I *do* want the submitter to get a sense of how the next branch can avoid those issues.
(2) Documentation and test changes implied by your code changes should go in the same branch. In other projects I usually commit docstring changes with the code change, and use two more commits, one for standalone docs and one for unit tests.
+1. This is actually something I wish vcses would handle better. Maybe there's git magic that would make this workflow better, but here's what I do when reviewing a merge proposal (most relevantly, bug fixes):
Run the full test suite with the full branch merged, but not yet committed. If there are *any* failures, the mp gets Needs Fixing'd.
Unapply the fix, and run the test suite. I should now see the new tests, and only the new tests fail.
Review the tests; do they actually test what they claim, and do they actually test the new code?
Reapply the fix. Everything should pass again.
I can do this with bzr shelve but it's a little clunky. It would be kind of
cool if TDD could be evident somehow in the branch, maybe e.g. as separate
commits. git rebase --interactive might be promising.
(3) Unrelated documentation changes (eg, a typo you notice in another function's docstring, or you want to add a docstring to an undocumented function that you had to study) should go in a separate *branch*. I usually have a branch just to collect these small improvements, and push them (or submit a merge request, depending on the project workflow) all at once.
+1
These practices are noticably tedious for the committer, but I find they greatly improve the usefulness of commit logs and the readability of diffs. It's not officially in the Zen of Python, but widely acknowledged, that Python should be written with the assumption that the code will be read many thousand times more often than it's written.
Absolutely. Really great advice, Steve.
Cheers, -Barry
participants (5)
-
Ana Badescu -
Andrew Stuart -
Barry Warsaw -
Stephen J. Turnbull -
Terri Oda