APIReview - Revision history

JaroslavTulach: /* What if it is Too Late? */

2016-07-17T13:31:23Z

What if it is Too Late?

←Older revision		Revision as of 13:31, 17 July 2016
Line 68:		Line 68:

	Cherry pick the [[good]] parts and approve them first? Yeah,		Cherry pick the [[good]] parts and approve them first? Yeah,
-	that is probably what [[I]] try: otherwise [[I]] am afraid that by commenting on	+	that is probably what [[I]]'ll try: otherwise [[I]] am afraid that by commenting on
	details of completely mis-designed subsystems, there is a high chance that the		details of completely mis-designed subsystems, there is a high chance that the
-	architecture ~~directions~~ would be lost and ~~authors may think that it is enough to do just~~	+	needed architecture changes would be lost in discussion about naming and code formatting.
-	~~a small bug-fixes rather than starting from scratch~~.	+

	Wish [[I\|me]] luck.		Wish [[I\|me]] luck.

JaroslavTulach: /* What if it is Too Late? */

2016-07-17T13:30:09Z

What if it is Too Late?

←Older revision		Revision as of 13:30, 17 July 2016
Line 65:		Line 65:
	The question is what to do with reviews that qualify for a standard review and are		The question is what to do with reviews that qualify for a standard review and are
	way too big? [[I]] don't know for sure. Return back and start from scratch?		way too big? [[I]] don't know for sure. Return back and start from scratch?
-	Probably useless. Cherry pick the [[good]] parts and approve them first? Yeah,	+	Probably useless, there is usually something good in such reviews.
		+
		+	Cherry pick the [[good]] parts and approve them first? Yeah,
	that is probably what [[I]] try: otherwise [[I]] am afraid that by commenting on		that is probably what [[I]] try: otherwise [[I]] am afraid that by commenting on
-	details, ~~the~~ high ~~level changes in~~ architecture directions would be lost.	+	details of completely mis-designed subsystems, there is a high chance that the
		+	architecture directions would be lost and authors may think that it is enough to do just
		+	a small bug-fixes rather than starting from scratch.

	Wish [[I\|me]] luck.		Wish [[I\|me]] luck.

JaroslavTulach: /* One Day Preparation */

2016-07-17T13:27:42Z

One Day Preparation

←Older revision		Revision as of 13:27, 17 July 2016
Line 53:		Line 53:
	can finish the whole work, then it is eligible for ''fasttrack review'' - if not,		can finish the whole work, then it is eligible for ''fasttrack review'' - if not,
	it is probably better to perform deeper/standard review. Which is fine as [[I]] usually only have:		it is probably better to perform deeper/standard review. Which is fine as [[I]] usually only have:
-	[[API]] methods, their documentation and tests showing the sample usage ~~and ask for~~	+	[[API]] methods, their documentation and tests showing the sample usage (but failing).
-	review of ~~such concept~~. ~~Then [[I]] feel [[I]] have something~~ material, but not ~~that~~	+	That is often the best way to
-	much, so the advices [[I]] can still be easily accumulated into the design.	+	review of the concepts. There is some material, but not too
		+	much, so the advices from the [[APIReview]] can still be easily accumulated into the design.

-	Sometimes it make take longer~~, maybe~~ even a week, but	+	Sometimes it make take longer to prepare the ''inception'' material. Maybe even a week, but
-	spending more than a week on a preparation of inception materials is too much.	+	spending more than a week on a preparation of inception materials is a way too much.

	== What if it is Too Late? ==		== What if it is Too Late? ==

JaroslavTulach: /* One Day Preparation */

2016-07-17T13:25:33Z

One Day Preparation

←Older revision		Revision as of 13:25, 17 July 2016
Line 52:		Line 52:
	[[I]] usually try to spend about a day to prepare the review material. If [[I]]		[[I]] usually try to spend about a day to prepare the review material. If [[I]]
	can finish the whole work, then it is eligible for ''fasttrack review'' - if not,		can finish the whole work, then it is eligible for ''fasttrack review'' - if not,
-	it is probably to do deeper/standard review ~~and~~ as ~~such [[I]] take what~~ [[I]] have:	+	it is probably better to perform deeper/standard review. Which is fine as [[I]] usually only have:
	[[API]] methods, their documentation and tests showing the sample usage and ask for		[[API]] methods, their documentation and tests showing the sample usage and ask for
	review of such concept. Then [[I]] feel [[I]] have something material, but not that		review of such concept. Then [[I]] feel [[I]] have something material, but not that

JaroslavTulach: /* Don't bother me with Code! */

2016-07-17T13:24:31Z

Don't bother me with Code!

←Older revision		Revision as of 13:24, 17 July 2016
Line 43:		Line 43:
	author happy.		author happy.

-	For these reasons the [[NetBeans]] recommends to start with [[~~usecases~~]] and review them	+	For these reasons the [[NetBeans]] recommends to start with [[usecase]]s and review them
-	as soon as possible. Once there is an agreement on the [[~~usecases~~]] - e.g. the raw direction for	+	as soon as possible. Once there is an agreement on the [[usecase]]s - e.g. the raw direction for
	solving them is understood, it is much more likely the result that comes out of the full development		solving them is understood, it is much more likely the result that comes out of the full development
	is going to be generally acceptable.		is going to be generally acceptable.

JaroslavTulach: /* Don't bother me with Code! */

2016-07-17T13:24:13Z

Don't bother me with Code!

←Older revision		Revision as of 13:24, 17 July 2016
Line 43:		Line 43:
	author happy.		author happy.

-	For these reasons the [[NetBeans]] recommends to start with [[~~UseCases~~]] and review them	+	For these reasons the [[NetBeans]] recommends to start with [[usecases]] and review them
-	as soon as possible. Once there is an agreement on ~~them and thus~~ the raw direction for	+	as soon as possible. Once there is an agreement on the [[usecases]] - e.g. the raw direction for
-	solving them is understood, it is much more likely the result that comes out of ~~that~~	+	solving them is understood, it is much more likely the result that comes out of the full development
-	is going to be ~~generaly~~ acceptable.	+	is going to be generally acceptable.

	==== One Day Preparation ====		==== One Day Preparation ====

JaroslavTulach: /* Show me the Code! */

2016-07-17T13:20:50Z

Show me the Code!

←Older revision		Revision as of 13:20, 17 July 2016
Line 23:		Line 23:

	In short, when proposing small, compatible additions to existing APIs, doing that		In short, when proposing small, compatible additions to existing APIs, doing that
-	as an [[API Patch]] is the best style of review. [[NetBeans]] call that ~~'''Fast Track'''~~ [[netbeans:APIReview]].	+	as an [[API Patch]] is the best style of review. [[NetBeans]] call that [[netbeans:APIReviewSteps#Fast-Track_Review\|Fast Track APIReview]].

	==== Don't bother me with Code! ====		==== Don't bother me with Code! ====

JaroslavTulach: /* Show me the Code! */

2016-07-17T13:19:46Z

Show me the Code!

←Older revision		Revision as of 13:19, 17 July 2016
Line 23:		Line 23:

	In short, when proposing small, compatible additions to existing APIs, doing that		In short, when proposing small, compatible additions to existing APIs, doing that
-	as ~~a patch~~ is the best style of review. [[NetBeans]] call that '''Fast Track''' [[netbeans:APIReview]].	+	as an [[API Patch]] is the best style of review. [[NetBeans]] call that '''Fast Track''' [[netbeans:APIReview]].

	==== Don't bother me with Code! ====		==== Don't bother me with Code! ====

JaroslavTulach: /* Show me the Code! */

2016-07-17T13:19:08Z

Show me the Code!

←Older revision		Revision as of 13:19, 17 July 2016
Line 18:		Line 18:
	documentation is [[good]] they know what is the purpose of the test.		documentation is [[good]] they know what is the purpose of the test.

-	Also creating such patch is usually easier than long ~~propse~~ sections describing of what	+	Also creating such patch is usually easier than long prose sections describing of what
	could be done without showing how. At the end most of the prose sections should become		could be done without showing how. At the end most of the prose sections should become
	part of the [[Javadoc]] documentation - thus one can include them in the patch as well.		part of the [[Javadoc]] documentation - thus one can include them in the patch as well.

JaroslavTulach: /* Show me the Code! */

2016-07-17T13:18:08Z

Show me the Code!

←Older revision		Revision as of 13:18, 17 July 2016
Line 8:		Line 8:
	==== Show me the Code! ====		==== Show me the Code! ====

-	When proposing small change or enhancement, it is preferrable to do it with ~~a patch~~ to existing	+	When proposing small change or enhancement, it is preferrable to do it with an [[API Patch]] to existing
	codebase. As Linus Torwalds once put it: ''talk is cheap, show me the code!''		codebase. As Linus Torwalds once put it: ''talk is cheap, show me the code!''