API Patch - Revision history

JaroslavTulach: /* No Bugs in Already Released APIs */

2026-01-20T08:38:50Z

No Bugs in Already Released APIs

←Older revision		Revision as of 08:38, 20 January 2026
Line 12:		Line 12:
	==== No Bugs in Already Released [[API]]s ====		==== No Bugs in Already Released [[API]]s ====

-	The above attitude can probably only be applied to [[API]]s (although [~~https://web.archive.org/web/20110712084057/http://testobsessed.com/2009/03/13/handling-bugs-in-an-agile-context/~~ similar attempts may be observed] in Agile movement too). We can expect those reporting nontrivial issues against [[API]] to have some level of engagement (e.g. be able to write a code and/or test). However if you provide end user functionality you may need to treat your users differently.	+	The above attitude can probably only be applied to [[API]]s (although [[OwnerOfBugs\|similar attempts may be observed]] in Agile movement too). We can expect those reporting nontrivial issues against [[API]] to have some level of engagement (e.g. be able to write a code and/or test). However if you provide end user functionality you may need to treat your users differently.

	In an [[API]] (where [[BackwardCompatibility]] is the primary concern), there are either trivial bugs (exceptions at unexpected places) or there are ''features''. After a release (due to the [[BackwardCompatibility]] implications) every bug (usually a report that something is not nice, beautiful or [[rationalistic]] enough) turns into a feature.		In an [[API]] (where [[BackwardCompatibility]] is the primary concern), there are either trivial bugs (exceptions at unexpected places) or there are ''features''. After a release (due to the [[BackwardCompatibility]] implications) every bug (usually a report that something is not nice, beautiful or [[rationalistic]] enough) turns into a feature.

JaroslavTulach: /* No Bugs in Already Released APIs */

2026-01-20T07:44:26Z

No Bugs in Already Released APIs

←Older revision		Revision as of 07:44, 20 January 2026
Line 16:		Line 16:
	In an [[API]] (where [[BackwardCompatibility]] is the primary concern), there are either trivial bugs (exceptions at unexpected places) or there are ''features''. After a release (due to the [[BackwardCompatibility]] implications) every bug (usually a report that something is not nice, beautiful or [[rationalistic]] enough) turns into a feature.		In an [[API]] (where [[BackwardCompatibility]] is the primary concern), there are either trivial bugs (exceptions at unexpected places) or there are ''features''. After a release (due to the [[BackwardCompatibility]] implications) every bug (usually a report that something is not nice, beautiful or [[rationalistic]] enough) turns into a feature.

-	As such reproducing and fixing a bug in an [[API]] requires different attitude. Encouraging community to seek for bugs in an [[API]] by providing ~~patches~~ to tests demonstrating wrong behavior is the [[good\|best way]] to make the [[API]] really usable. On the other hand, the maintainer needs to be careful to not accept bad ~~patches~~. The [[Teamwork\|chapter 16]] describes strategies to evaluate quality of submitted ~~patches~~ and separate the perils from dust. But the rules are simple. An [[API]] bug report has to be [[good]]:	+	As such reproducing and fixing a bug in an [[API]] requires different attitude. Encouraging community to seek for bugs in an [[API]] by providing [[patch]]es to tests demonstrating wrong behavior is the [[good\|best way]] to make the [[API]] really usable. On the other hand, the maintainer needs to be careful to not accept bad [[patch]]es. The [[Teamwork\|chapter 16]] describes strategies to evaluate quality of submitted [[patch]]es and separate the perils from dust. But the rules are simple. An [[API]] bug report has to be [[good]]:
	* it has to be easy to verify the problem is there - the best way to do it is to have an automated test that can just be executed and the misbehavior reveals itself automatically		* it has to be easy to verify the problem is there - the best way to do it is to have an automated test that can just be executed and the misbehavior reveals itself automatically
	* when the fix is applied (and subsequent changes are made in future) one can easily verify that the original intentions are still valid - again automatic test is your best friend		* when the fix is applied (and subsequent changes are made in future) one can easily verify that the original intentions are still valid - again automatic test is your best friend
-	* the change needs to be cool - well, [[API]] writers are glad to accept ~~patches~~, if they are [[good]] (notice the self reference in the definition).	+	* the change needs to be cool - well, [[API]] writers are glad to accept [[patch]]es, if they are [[good]] (notice the self reference in the definition).

-	The above shows why ''maintaining of an [[API]] may be simpler than maintaining similar functionality without an [[API]]''. There is just one requirement: the [[API]] owner needs to be ready to accept the [[good]] ~~patches~~. It needs to encourage the community to write high quality [[API Patch]]es. Dear [[NetBeans]] [[API]] users, this wiki page is my attempt to provide such encouragement. I am looking forward your ~~patches~~ for openide.explorer, openide.nodes, openide.loaders, etc.	+	The above shows why ''maintaining of an [[API]] may be simpler than maintaining similar functionality without an [[API]]''. There is just one requirement: the [[API]] owner needs to be ready to accept the [[good]] [[patch]]es. It needs to encourage the community to write high quality [[API Patch]]es. Dear [[NetBeans]] [[API]] users, this wiki page is my attempt to provide such encouragement. I am looking forward your [[patch]]es for openide.explorer, openide.nodes, openide.loaders, etc.

	==== Accepting Unacceptable ====		==== Accepting Unacceptable ====

JaroslavTulach: /* No Bugs in Already Released APIs */

2026-01-20T07:42:31Z

No Bugs in Already Released APIs

←Older revision		Revision as of 07:42, 20 January 2026
Line 12:		Line 12:
	==== No Bugs in Already Released [[API]]s ====		==== No Bugs in Already Released [[API]]s ====

-	The above attitude can probably only be applied to [[API]]s (although [http://testobsessed.com/2009/03/13/handling-bugs-in-an-agile-context/ similar attempts may be observed] in Agile movement too). We can expect those reporting nontrivial issues against [[API]] to have some level of engagement (e.g. be able to write a code and/or test). However if you provide end user functionality you may need to treat your users differently.	+	The above attitude can probably only be applied to [[API]]s (although [https://web.archive.org/web/20110712084057/http://testobsessed.com/2009/03/13/handling-bugs-in-an-agile-context/ similar attempts may be observed] in Agile movement too). We can expect those reporting nontrivial issues against [[API]] to have some level of engagement (e.g. be able to write a code and/or test). However if you provide end user functionality you may need to treat your users differently.

	In an [[API]] (where [[BackwardCompatibility]] is the primary concern), there are either trivial bugs (exceptions at unexpected places) or there are ''features''. After a release (due to the [[BackwardCompatibility]] implications) every bug (usually a report that something is not nice, beautiful or [[rationalistic]] enough) turns into a feature.		In an [[API]] (where [[BackwardCompatibility]] is the primary concern), there are either trivial bugs (exceptions at unexpected places) or there are ''features''. After a release (due to the [[BackwardCompatibility]] implications) every bug (usually a report that something is not nice, beautiful or [[rationalistic]] enough) turns into a feature.

JaroslavTulach: /* Paying More Attention to Your Issues */

2026-01-20T07:40:54Z

Paying More Attention to Your Issues

←Older revision		Revision as of 07:40, 20 January 2026
Line 8:		Line 8:
	Review process]] that allows you to contribute.		Review process]] that allows you to contribute.

-	The number of [[API]] issues will get down to manageable level in a few weeks. When we get there, it will be possible to pay more attention to newly reported inquiries and deal with them in more polite way. Issues shall not be left laying around for few releases unnoticed anymore. At the end we shall all benefit from the radical elimination of the number of open issues in [[NetBeans]] [[API]]s.	+	The number of [[API]] issues will get down to manageable level in a few weeks. When we get there, it will be possible to pay more attention to newly reported inquiries and deal with them in a more polite way. Issues shall not be left laying around for few releases unnoticed anymore. At the end we shall all benefit from the radical elimination of the number of open issues in [[NetBeans]] [[API]]s.

	==== No Bugs in Already Released [[API]]s ====		==== No Bugs in Already Released [[API]]s ====

JaroslavTulach: /* Paying More Attention to Your Issues */

2010-04-18T08:00:27Z

Paying More Attention to Your Issues

←Older revision		Revision as of 08:00, 18 April 2010
Line 8:		Line 8:
	Review process]] that allows you to contribute.		Review process]] that allows you to contribute.

-	The number of [[API]] issues will get down to manageable level in a few weeks. When we get there, it will be possible to pay more attention to reported inquiries and deal with them in more polite way. Issues shall not be left laying around for few	+	The number of [[API]] issues will get down to manageable level in a few weeks. When we get there, it will be possible to pay more attention to newly reported inquiries and deal with them in more polite way. Issues shall not be left laying around for few releases unnoticed anymore. At the end we shall all benefit from the radical elimination of the number of open issues in [[NetBeans]] [[API]]s.
-	releases unnoticed anymore. At the end we shall all benefit from the radical elimination of the number of open issues in [[NetBeans]] [[API]]s.	+

	==== No Bugs in Already Released [[API]]s ====		==== No Bugs in Already Released [[API]]s ====

JaroslavTulach: /* Accepting Unacceptable */

2010-04-18T07:55:41Z

Accepting Unacceptable

←Older revision		Revision as of 07:55, 18 April 2010
Line 26:		Line 26:
	==== Accepting Unacceptable ====		==== Accepting Unacceptable ====

-	There is a little coding trick, called [[CodeInjection\|code injection]], ~~that can help~~ balance the need for extensibility while lowering overall [[Cost of Ownership]]. While using [[API]] [[CodeInjection]] it is basically possible to donate [[API Patch]] to any [[API]].	+	There are cases when [[API]] owners don't want to accept some contribution. This is unfortunate, but it may happen. Then please use this little coding trick, called [[CodeInjection\|code injection]], to balance the need for extensibility while lowering overall [[Cost of Ownership]]. While using [[API]] [[CodeInjection]] it is basically possible to donate [[API Patch]] to any [[API]].


	<comments/>		<comments/>

JaroslavTulach: /* No Bugs in Already Released APIs */

2010-04-18T07:54:39Z

No Bugs in Already Released APIs

←Older revision		Revision as of 07:54, 18 April 2010
Line 21:		Line 21:
	* when the fix is applied (and subsequent changes are made in future) one can easily verify that the original intentions are still valid - again automatic test is your best friend		* when the fix is applied (and subsequent changes are made in future) one can easily verify that the original intentions are still valid - again automatic test is your best friend
	* the change needs to be cool - well, [[API]] writers are glad to accept patches, if they are [[good]] (notice the self reference in the definition).		* the change needs to be cool - well, [[API]] writers are glad to accept patches, if they are [[good]] (notice the self reference in the definition).
		+
		+	The above shows why ''maintaining of an [[API]] may be simpler than maintaining similar functionality without an [[API]]''. There is just one requirement: the [[API]] owner needs to be ready to accept the [[good]] patches. It needs to encourage the community to write high quality [[API Patch]]es. Dear [[NetBeans]] [[API]] users, this wiki page is my attempt to provide such encouragement. I am looking forward your patches for openide.explorer, openide.nodes, openide.loaders, etc.

	==== Accepting Unacceptable ====		==== Accepting Unacceptable ====

JaroslavTulach: /* No Bugs in Already Released APIs */

2010-04-18T07:46:12Z

No Bugs in Already Released APIs

←Older revision		Revision as of 07:46, 18 April 2010
Line 17:		Line 17:
	In an [[API]] (where [[BackwardCompatibility]] is the primary concern), there are either trivial bugs (exceptions at unexpected places) or there are ''features''. After a release (due to the [[BackwardCompatibility]] implications) every bug (usually a report that something is not nice, beautiful or [[rationalistic]] enough) turns into a feature.		In an [[API]] (where [[BackwardCompatibility]] is the primary concern), there are either trivial bugs (exceptions at unexpected places) or there are ''features''. After a release (due to the [[BackwardCompatibility]] implications) every bug (usually a report that something is not nice, beautiful or [[rationalistic]] enough) turns into a feature.

-	As such reproducing and fixing a bug in an [[API]] requires different attitude. Encouraging community to seek for bugs in an [[API]] by providing patches to tests demonstrating wrong behavior is a best way to make the [[API]] really usable. On the other hand, the maintainer needs to be careful to not accept bad patches. The [[Teamwork\|chapter 16]] describes strategies to evaluate quality of submitted patches and separate the perils from dust. But the rules are simple. An [[API]] bug report has to be [[good]]:	+	As such reproducing and fixing a bug in an [[API]] requires different attitude. Encouraging community to seek for bugs in an [[API]] by providing patches to tests demonstrating wrong behavior is the [[good\|best way]] to make the [[API]] really usable. On the other hand, the maintainer needs to be careful to not accept bad patches. The [[Teamwork\|chapter 16]] describes strategies to evaluate quality of submitted patches and separate the perils from dust. But the rules are simple. An [[API]] bug report has to be [[good]]:
	* it has to be easy to verify the problem is there - the best way to do it is to have an automated test that can just be executed and the misbehavior reveals itself automatically		* it has to be easy to verify the problem is there - the best way to do it is to have an automated test that can just be executed and the misbehavior reveals itself automatically
	* when the fix is applied (and subsequent changes are made in future) one can easily verify that the original intentions are still valid - again automatic test is your best friend		* when the fix is applied (and subsequent changes are made in future) one can easily verify that the original intentions are still valid - again automatic test is your best friend

JaroslavTulach: /* No Bugs in Already Released APIs */

2010-04-18T07:45:24Z

No Bugs in Already Released APIs

←Older revision		Revision as of 07:45, 18 April 2010
Line 15:		Line 15:
	The above attitude can probably only be applied to [[API]]s (although [http://testobsessed.com/2009/03/13/handling-bugs-in-an-agile-context/ similar attempts may be observed] in Agile movement too). We can expect those reporting nontrivial issues against [[API]] to have some level of engagement (e.g. be able to write a code and/or test). However if you provide end user functionality you may need to treat your users differently.		The above attitude can probably only be applied to [[API]]s (although [http://testobsessed.com/2009/03/13/handling-bugs-in-an-agile-context/ similar attempts may be observed] in Agile movement too). We can expect those reporting nontrivial issues against [[API]] to have some level of engagement (e.g. be able to write a code and/or test). However if you provide end user functionality you may need to treat your users differently.

-	In an [[API]] (where [[BackwardCompatibility]] is the primary concern), there either trivial bugs (exceptions at unexpected places) or there are ''features''. After a release (due to the [[BackwardCompatibility]] implications) every bug (usually a report that something is not nice, beautiful or [[rationalistic]] enough) turns into a feature.	+	In an [[API]] (where [[BackwardCompatibility]] is the primary concern), there are either trivial bugs (exceptions at unexpected places) or there are ''features''. After a release (due to the [[BackwardCompatibility]] implications) every bug (usually a report that something is not nice, beautiful or [[rationalistic]] enough) turns into a feature.

	As such reproducing and fixing a bug in an [[API]] requires different attitude. Encouraging community to seek for bugs in an [[API]] by providing patches to tests demonstrating wrong behavior is a best way to make the [[API]] really usable. On the other hand, the maintainer needs to be careful to not accept bad patches. The [[Teamwork\|chapter 16]] describes strategies to evaluate quality of submitted patches and separate the perils from dust. But the rules are simple. An [[API]] bug report has to be [[good]]:		As such reproducing and fixing a bug in an [[API]] requires different attitude. Encouraging community to seek for bugs in an [[API]] by providing patches to tests demonstrating wrong behavior is a best way to make the [[API]] really usable. On the other hand, the maintainer needs to be careful to not accept bad patches. The [[Teamwork\|chapter 16]] describes strategies to evaluate quality of submitted patches and separate the perils from dust. But the rules are simple. An [[API]] bug report has to be [[good]]:

JaroslavTulach: /* No Bugs in Already Released APIs */

2010-04-18T07:43:53Z

No Bugs in Already Released APIs

←Older revision		Revision as of 07:43, 18 April 2010
Line 15:		Line 15:
	The above attitude can probably only be applied to [[API]]s (although [http://testobsessed.com/2009/03/13/handling-bugs-in-an-agile-context/ similar attempts may be observed] in Agile movement too). We can expect those reporting nontrivial issues against [[API]] to have some level of engagement (e.g. be able to write a code and/or test). However if you provide end user functionality you may need to treat your users differently.		The above attitude can probably only be applied to [[API]]s (although [http://testobsessed.com/2009/03/13/handling-bugs-in-an-agile-context/ similar attempts may be observed] in Agile movement too). We can expect those reporting nontrivial issues against [[API]] to have some level of engagement (e.g. be able to write a code and/or test). However if you provide end user functionality you may need to treat your users differently.

-	In an [[API]] (where [[BackwardCompatibility]] is the primary concern), there either trivial bugs (exceptions at unexpected places) or there are ''features''. After a release (due to the [[BackwardCompatibility]] implications) every bug turns into a feature.	+	In an [[API]] (where [[BackwardCompatibility]] is the primary concern), there either trivial bugs (exceptions at unexpected places) or there are ''features''. After a release (due to the [[BackwardCompatibility]] implications) every bug (usually a report that something is not nice, beautiful or [[rationalistic]] enough) turns into a feature.

-	As such reproducing and fixing a bug in an [[API]] requires different ~~attitudes~~. Encouraging community to seek for bugs in an [[API]] ~~and provide~~ patches to ~~its~~ behavior is a best way to make the [[API]] really usable. On the other hand, the maintainer needs to be careful to not accept bad patches. The [[Teamwork\|chapter 16]] describes strategies to evaluate quality of submitted patches and separate the perils from dust. But the rules are simple an [[API]] bug report has to be [[good]]:	+	As such reproducing and fixing a bug in an [[API]] requires different attitude. Encouraging community to seek for bugs in an [[API]] by providing patches to tests demonstrating wrong behavior is a best way to make the [[API]] really usable. On the other hand, the maintainer needs to be careful to not accept bad patches. The [[Teamwork\|chapter 16]] describes strategies to evaluate quality of submitted patches and separate the perils from dust. But the rules are simple. An [[API]] bug report has to be [[good]]:
	* it has to be easy to verify the problem is there - the best way to do it is to have an automated test that can just be executed and the misbehavior reveals itself automatically		* it has to be easy to verify the problem is there - the best way to do it is to have an automated test that can just be executed and the misbehavior reveals itself automatically
	* when the fix is applied (and subsequent changes are made in future) one can easily verify that the original intentions are still valid - again automatic test is your best friend		* when the fix is applied (and subsequent changes are made in future) one can easily verify that the original intentions are still valid - again automatic test is your best friend