| ←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 ==== |