You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@netbeans.apache.org by vi...@apache.org on 2020/03/17 19:34:42 UTC
[netbeans-website] branch master updated: [NETBEANS-3704] Wiki
pages required by apidoc
This is an automated email from the ASF dual-hosted git repository.
vieiro pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/netbeans-website.git
The following commit(s) were added to refs/heads/master by this push:
new fbc9d96 [NETBEANS-3704] Wiki pages required by apidoc
fbc9d96 is described below
commit fbc9d967db636f214eae64f9128243ed247cc987
Author: Antonio Vieiro <vi...@users.noreply.github.com>
AuthorDate: Tue Mar 17 20:34:36 2020 +0100
[NETBEANS-3704] Wiki pages required by apidoc
Some important web pages related to API management. Somewhat outdated, but worth keeping.
---
.../src/content/wiki/APIDevelopment.asciidoc | 432 +++++++++++
.../src/content/wiki/APIReviews.asciidoc | 112 +++
.../src/content/wiki/APITest.asciidoc | 47 ++
.../src/content/wiki/API_Design.asciidoc | 791 +++++++++++++++++++++
.../src/content/wiki/API_Stability.asciidoc | 141 ++++
.../src/content/wiki/Authenticator.asciidoc | 121 ++++
.../wiki/BackwardCompatibilityPatches.asciidoc | 292 ++++++++
.../wiki/BackwardCompatibilityTesting.asciidoc | 116 +++
.../wiki/BugtrackingAPISPIUseCases.asciidoc | 251 +++++++
.../src/content/wiki/BugtrackingCookbook.asciidoc | 260 +++++++
.../src/content/wiki/BuildSystemHowTo.asciidoc | 523 ++++++++++++++
.../src/content/wiki/CompatibilityPolicy.asciidoc | 245 +++++++
.../src/content/wiki/Filter_Menu.png | Bin 0 -> 6892 bytes
.../src/content/wiki/Fitness.asciidoc | 73 ++
.../src/content/wiki/FitnessMemoryLeaks.asciidoc | 155 ++++
.../content/wiki/FitnessViaPartnership.asciidoc | 115 +++
.../src/content/wiki/FitnessViaPostMortem.asciidoc | 168 +++++
.../content/wiki/FitnessViaTimersCounter.asciidoc | 125 ++++
.../src/content/wiki/FolderOrdering103187.asciidoc | 396 +++++++++++
.../src/content/wiki/Group_Priority.png | Bin 0 -> 24481 bytes
.../src/content/wiki/HtmlUIForTemplates.asciidoc | 269 +++++++
.../src/content/wiki/NbmIdioms.asciidoc | 403 +++++++++++
.../src/content/wiki/ParsingAPI.asciidoc | 197 +++++
.../wiki/Profileme_FitnessViaPartnership.png | Bin 0 -> 89345 bytes
.../content/wiki/RunConfigurations49636.asciidoc | 156 ++++
.../src/content/wiki/RuntimeWatches.png | Bin 0 -> 13620 bytes
.../src/content/wiki/SigTest.asciidoc | 235 ++++++
.../src/content/wiki/SignatureTest.asciidoc | 230 ++++++
.../content/wiki/TaskDashboardDesignSpec.asciidoc | 134 ++++
.../src/content/wiki/TaskDashboard_Menus.png | Bin 0 -> 19138 bytes
.../content/wiki/TaskManagementUseCases.asciidoc | 569 +++++++++++++++
.../src/content/wiki/Task_Dashboard_MarkedUp.png | Bin 0 -> 24120 bytes
.../src/content/wiki/VersioningPolicy.asciidoc | 315 ++++++++
.../wiki/notification_FitnessViaPostMortem.png | Bin 0 -> 4035 bytes
netbeans.apache.org/src/content/wiki/yes.png | Bin 0 -> 3640 bytes
35 files changed, 6871 insertions(+)
diff --git a/netbeans.apache.org/src/content/wiki/APIDevelopment.asciidoc b/netbeans.apache.org/src/content/wiki/APIDevelopment.asciidoc
new file mode 100644
index 0000000..02b0077
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/APIDevelopment.asciidoc
@@ -0,0 +1,432 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+
+= API_Development
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: API Development
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+[[Overview]]
+== Overview
+
+The link:https://netbeans.apache.org[NetBeans] project provides a rich set of
+link:http://bits.netbeans.org/dev/javadoc/[APIs] that is being developed as
+part of work of various groups. By distributing development of the
+link:API_Design.asciidoc[API]s to multiple people we can increase the amount of designed,
+reviewed, implemented, tuned and maintained contracts but as each module is
+developed by a different person, there is a challenge in providing
+link:API_Design.asciidoc[API]s of the same quality, designed by using the same patterns
+and documented in a common way. This document describes the practices that
+should be used during the link:API_Design.asciidoc[API] development, so
+link:https://netbeans.apache.org[NetBeans] can produce link:API_Design.asciidoc[API]s that will stand
+the test of time and preserve investments made by its customers.
+
+
+[[Describing_APIs]]
+=== Describing APIs
+
+We understand the APIs as every aspect another piece of system can depend on and not just method signature. That is why providing documentation in form of javadoc is not usually be enough. Instead NetBeans projects use document generated from answers to Architecture Questions as main entry point. The questions provide guidance to the module owner and help him investigate architecture of his own module. By answering them the owner is supposed to realize and discover various aspects that o [...]
+
+|===
+|Interface Name |Stability Classification |Specified in What Document?
+
+|ProviderRegistrationRemoval |link:API_Design.asciidoc#devel[Under Development] |link:https://bits.netbeans.org/dev/javadoc/org-openide-util/org/openide/util/doc-files/api.html#service-lookup[api.html]
+
+|LookupAPI |link:API_Design.asciidoc#official[Official] |link:https://bits.netbeans.org/dev/javadoc/org-openide-util/org/openide/util/doc-files/api.html#lookup[[lookup]]
+
+|LookupSPI |link:API_Design.asciidoc#official[Official] |link:https://bits.netbeans.org/dev/javadoc/org-openide-util/org/openide/util/lookup/package-frame.html[package-frame.html]
+
+|Set of property APIs |Individual |link:https://bits.netbeans.org/dev/javadoc/org-openide-util/architecture-summary.html#group-property[table with definitions]
+|===
+
+
+[[Setting_up_the_infrastructure]]
+=== Setting up the infrastructure
+
+If you write a NetBeans module you may want to setup the right layout of files
+first.
+
+The default infrastructure (link:https://github.com/apache/netbeans/blob/master/nbbuild/templates/common.xml[nbbuild/templates/common.xml]
+and link:https://github.com/apache/netbeans/blob/master/nbbuild/templates/projectized.xml[nbbuild/templates/projectized.xml])
+let you do various tweaks, but usually it is easier to just use the expected
+default layout (currently described in
+link:https://github.com/apache/netbeans/blob/master/harness/apisupport.harness/release/README[harness/apisupport.harness/release/README]).
+
+The documentation related files shall be organized as follows:
+
+[source,bash,subs="{markup-in-source}"]
+----
+module_dir/src/ - directory with your sources
+module_dir/src/**/package.html - description of each package
+module_dir/src/**/doc-files/ - directory for special javadoc files
+module_dir/arch.xml - answers to architecture questions (see bellow)
+module_dir/apichanges.xml - description of the history of changes
+module_dir/nbproject/project.xml - project file with dependencies and other informations
+----
+
+The locations of arch.xml and apichanges.xml moreover has to be specified in
+link:https://github.com/apache/netbeans/blob/master/ide/projectapi/nbproject/project.properties[nbproject/project.properties]
+as follows:
+
+[source]
+----
+javadoc.arch=${basedir}/arch.xml
+javadoc.apichanges=${basedir}/apichanges.xml
+----
+
+
+[[Writing_the_documentation]]
+=== Writing the documentation
+
+
+
+. *Generate arch.xml* - open your project in NetBeans and select <em>Generate Architecture Description</em> from a context menu in projects tab. An empty, skeleton file will be generated. You can always reinvoke this target, if your answers are old, unanswered questions will be generated to the end of the file (the file shall stay well formated). When editing the file you can use <b>HTML tags</b>. Some of the answers may have autogenerated default answers (currently arch-where and dep-nb [...]
+. *Use <api/> tag* - this tag is one of the most important in the architecture file. Each use of the <api&gt tags generates new item into a table of API interfaces. This is the main entry point to the documentation, so use the tag a lot. Not just for a description of javadoc interfaces, but for everything. Remember that an api is link:API_Design.asciidoc[any feature that someone else rely on]. Describe DTDs, properties, files or layers you read, formats or protocols that you communic [...]
+.. *name* - the name of the API, DTD or property
+.. *group* - the group that this API belongs. For example "property", "java", "dtd", "layer" and possibly others. As we are writing in java the attribute can be omitted and the default value is "java".
+.. *type* - you can either use someone else API ("import") or offer someone else dependency on your behavior ("export").
+.. *category* - shall contain a name from the enumeration (`official`, `stable`, `devel`, `third`, `standard`, `friend`, `private`, `deprecated`) in the meaning described link:API_Design.asciidoc#categories[here].
+.. *url* - shall refer to a document describing the API, if available otherwise one can insert additional comments into the body between the `<api>` and `</api>`.
+
+An example is available here:
+
+[source, xml]
+----
+<api name="identification"
+ group="dtd"
+ type="import or export"
+ category="stable"
+ url="where is the description">
+ Possibly some additional description to the API which may be skipped.
+</api>
+----
+
+The interfaces in the table are grouped by the group of the API and marked in
+the HTML text as `<a name="group-name" />` so a reference to these tables can
+be made by using `<a href="#group-name" />`.
+
+. *Use <usecase> tag* - when answering "arch-usecases" question, surround the
+paragraphs describing the way to use your API with `<usecase name="..."
+id="...">` and `</usecase>`. That way your paragraph will get correct heading
+in the link:https://bits.netbeans.org/dev/javadoc/usecases.html[How to use
+certain NetBeans APIs] page. . *Answer "arch-what"* - the first sentence of
+your answer to "arch-what" is used as a short description in the
+link:https://bits.netbeans.org/dev/javadoc/overview-summary.html[overview page]
+so write it meaningfully. The full answer is then used in
+link:https://bits.netbeans.org/dev/javadoc/overview-summary.html#def-api-Terminal%20Emulator[the
+details] section, so again, make it real and useful description of your module.
+
+. *Link between documents* - important part of documentation is the description
+of context. It is not enough to say: "find this interfacein lookup". The reader
+may not know what "lookup" is, so it is better to hyperlink to its definition.
+You can use regular `<a href>` tag to link to other documents, for root of your
+javadoc use *@TOP@*. So link to lookup would be
+`@TOP@/org/openide/util/Lookup.html`.
+
+. *Link between classes* - consider making the prose section part of
+`package.html` file. Then you can use *@{link classname}* to address any class
+of your module or from modules you depend on.
+
+. *Link between Javadoc sets* - the context is often split between multiple
+modules. To allow links between them, the root of each module javadoc can be
+referred to as *@org-netbeans-the-module-code-base-name@*. So to link to lookup
+from another module one can use
+`@org-openide-util@/org/openide/util/Lookup.html` (the list of all currently
+known module name substitutions is available at
+link:https://github.com/apache/netbeans/blob/master/nbbuild/javadoctools/replaces.xml?content-type=text/plain[nbbuild/javadoctools/replaces.xml]).
+
+. *Use Relative Links* - please remove as much as possible of usages of
+non-relative links like
+link:http://www.netbeans.org/download/dev/javadoc/[http://www.netbeans.org/download/dev/javadoc/]
+and replace them with *@TOP@*, *@org-netbeans-module-name@* or *@JDK@* root
+points. The javadoc is being scanned for allowed and disallowed links (defined
+in
+link:https://github.com/apache/netbeans/blob/master/nbbuild/javadoctools/disallowed-links.xml[nbbuild/javadoctools/disallowed-links.xml])
+and violations cause the build run from IDE to fail. It is generally not
+recommended to refer to NetBeans website as the documentation shall be self
+contained, but if you find a URL that makes sence, feel free to add it to the
+link:https://github.com/apache/netbeans/blob/master/nbbuild/javadoctools/disallowed-links.xml[nbbuild/javadoctools/disallowed-links.xml])
+yourself. Btw. it seems better to use such pseudo root point than directly
+relative link as for example content of package.html is usually duplicated into
+more directories.
+
+. *Create apichanges* - important part of any api is history of its changes.
+That is why create and maintain the
+link:https://github.com/apache/netbeans/blob/master/platform/openide.loaders/apichanges.xml[apichanges.xml]
+as described in NetBeans link:VersioningPolicy.asciidoc[VersioningPolicy]. When you
+refer to a class that no longer exists inside an API change, you can use `<class ... link="no"/>`.
+
+. *Validate your documentation* - make sure the documentation format is correct
+(links point to valid places, XML files has valid syntax, etc.). This can be
+checked by invoking "Generate Javadoc" from the context menu. This builds the
+Javadoc and (in addition to invoking `ant javadoc` from command line) also
+checks for broken links and fails if there any - so make sure all Javadoc of
+modules you are referring to has already been generated.
+
+
+[[Publishing_Javadoc]]
+=== Publishing Javadoc
+
+All NetBeans project Javadoc sets are being daily regenerated and uploaded to
+the central link:https://bits.netbeans.org/dev/javadoc/[NetBeans API List].
+When your module can successfully build javadoc as described in previous
+section, it is time to consider adding it to the API list as well.
+
+To add it, you have to modify
+link:https://github.com/apache/netbeans/blob/master/nbbuild/build.properties[nbbuild/build.properties]
+and add own module into `config.fixedmodules.javadoc` property.
+
+Use
+[source, bash]
+----
+ant -f nbbuild/build.xml check-module-configs
+cvs -q diff nbbuild
+----
+
+to review your changes. Then verify that everything works correctly by rebuilding all Javadoc:
+
+[source, bash]
+----
+ant -f nbbuild/build.xml build-javadoc`
+----
+
+and if the build succeeds and really contains your module, prepare for
+committing your changes into CVS (check in the new `moduleconfigs.txt` too).
+Please note that three files in `nbbuild/javadoctools` shall be modified by
+addition of references to your module root. Verify that the additions are sane
+(e.g. contain no local references and look like the other lines in the files)
+and then commit the modified
+link:https://github.com/apache/netbeans/blob/master/nbbuild/build.properties[nbbuild/build.properties],
+link:https://github.com/apache/netbeans/blob/master/nbbuild/javadoctools/replaces.xml[nbbuild/javadoctools/replaces.xml],
+link:https://github.com/apache/netbeans/blob/master/nbbuild/javadoctools/links.xml[nbbuild/javadoctools/links.xml] and
+link:https://github.com/apache/netbeans/blob/master/nbbuild/javadoctools/properties.xml[nbbuild/javadoctools/properties.xml].
+
+
+[[Javadoc_Tips]]
+=== Javadoc Tips
+
+By default the basic overview page is generated based on content of your
+link:https://github.com/apache/netbeans/blob/master/apisupport/apisupport.project/arch.xml[arch.xml],
+link:https://github.com/apache/netbeans/blob/master/apisupport/apisupport.project/apichanges.xml[apichanges.xml] and
+link:https://github.com/apache/netbeans/blob/master/apisupport/apisupport.project/nbproject/project.xml[project.xml].
+
+To see an example, check the link:https://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/overview-summary.html[overview page of component palette api],
+that has the following structure:
+
+1. *Title and description* is taken from the `arch.xml` 's answer to question `arch-overall`.
+. *List of javadoc packages* is added by the default javadoc doclet.
+. *what is new section* lists five recent api changes listed in `apichanges.xml`. Always add at least one change as this document is used to generate what is link:https://bits.netbeans.org/dev/javadoc/apichanges.html[new for the whole release].
+. *List of usecases* is taken from the `arch.xml` answer to `arch-usecases` question. It shall contain the main introduction into the meaning and usage of the API. Links to javadoc classes and methods are welcomed. Also notice that the answer contributed to link:https://bits.netbeans.org/dev/javadoc/usecases.html[global page with usecases] for all NetBeans APIs.
+. *Implementation details* close the summary page. The contain answer to `arch-where` question, which shall contain link to NetBeans WebCVS with the module sources like link:https://github.com/apache/netbeans/blob/master/java/project/[https://github.com/apache/netbeans/blob/master/java/project/] for the link:https://github.com/apache/netbeans/blob/master/java/project/[java/project] module. Also an answer to `deploy-dependencies` arch question is generated so other modules know how to exp [...]
+
+*XXX* need to describe: `{@link ...}`, what `package.html` can and cannot do, `@inheritDoc`, etc.
+
+
+[[Reviewing_APIs]]
+== Reviewing APIs
+
+In order to ensure good enough quality of produced APIs there is a service
+provided to module writers - they can ask for an API review.
+
+It is required that every new API will be reviewed prior to integration into
+trunk. The exception from this rule is a `friend` API that is used only by
+modules within the same cluster (the module has to explicitly list its
+friends). In this case the review is recommended but not required.
+
+
+[[Why]]
+=== Why?
+
+The short answer to question why you should be interested in an architecture review is "because it will be useful". Useful to you, as you discover new possible solutions to your problems or mistakes in your design, that might appear later, when integrated together with the whole system or even in later versions, when problems with maintainability and extensibility can show up. It will be useful to the whole system as it will be composed from more stable components integrated in better wa [...]
+
+Nobody knows everything, but there is a lot of knowledge spread around. Architecture review is a way to get the people with pieces of knowledge together and cooperate in preventing us from repeating known mistakes and solving problems in the wrong way.
+
+Ask for advice through architecture review. It cannot hurt and it is likely going to be useful.
+
+
+[[What]]
+=== What?
+
+It is unlikely that the review team will do some coding for you. It is also unlikely that the reviewers are going to become domain experts and help you understand your users or your requirements. This is your task and you have to prepare these materials for the reviewers, as it is very likely they will ask you about these questions in order to verify that your way of solving problems of your users is really the right one.
+
+As a result of architecture review you can expect advices and help in identification of
+
+* link:API_Design.asciidoc#api[apis] that someone else could depend on,
+* design or implementation that might have performance problems,
+* influences of your solution on existing products or
+* influences of other products on your solution in future,
+* solutions that are solving something different than was the original goal and
+* other projects or efforts going around that might help you in solving your problems.
+
+More or less expect "just" a high level help.
+
+
+[[When]]
+=== When?
+
+Whenever you need architecture advice or clarification and because the charter of the team is mostly high level, it is reasonable to come for the initial opinion as soon as the architecture is visible so it can be reviewed. This usually means after answering the first (more general) set of the architecture questions which should be done before the actual start of implementation. At this point the high level advices are of some use, later it is always hard to change implementation [...]
+
+Of course things are likely change during implementation, but the high level direction given during this _inception_ stage are likely not going to be questioned then and only the newly discovered facts and differences from the original suggestions are going to be evaluated during the _before-commit_ review.
+
+
+[[How]]
+=== How?
+
+For details about the process see the Architecture Review Steps document or check the list of all reviews.
+
+
+[[Testing_APIs]]
+== Testing APIs
+
+
+[[Why_2]]
+=== Why?
+
+If an API is supposed to stand the test of time it has to preserve the functionality that others are using, it has to be backward compatible. Some tests for compatibility are easy, some require more work, but the testing is necessary otherwise nobody can guarantee quality when the API is evolving.
+
+<<sigtests,Signature tests>> are simple starting point, <<unittests,unit tests>> are very good for verifying the "contract" between a public API and its clients. Some people claim that unit tests are poorly named since they imply that they are QA's responsibility, but the development engineer is the one that really
+benefits with several advantages:
+
+* the tests provide an example of how the developer expects the API to be used.
+* Another is that when you run code coverage against a unit test suite, it shows surprising areas where there is code that isn't necessary to support the API, so one can easily remove those extra bits
+* Another interesting feature of unit tests is support of arrogance (which is part of all good programmers). So here's the best, most compelling reason for creating and relying on unit tests: you can much more confidently tell another engineer how wrong he is when he claims your code is breaking his!
+
+Read more about possible test patterns that we use and how they can contribute to improvements in quality of your module.
+
+
+[[sigtests]]
+=== Signature Tests
+
+There is an automated verification task that is executed after every daily build that checks signature of classes and their fields and methods and sends reports to link:http://netbeans.org/projects/www/lists/api-changes/archive[api-changes] mailing list. Its reports contain both incompatible and compatible changes. So one gets notified not only when something is broken, but also in case of accidental API change like addition of a method by forgetting to make it
+`private`.
+
+By default the tests check all classes in link:API_Design.asciidoc#official[official] packages. E.g.
+`org.openide.*`, `org.netbeans.api.*` and `org.netbeans.spi.*` and recently
+also `org.netbeans.jmi` that are part of modules included in daily build of
+standard IDE and also those that are daily uploaded to _Alpha Update Center_.
+
+That is why in order to have these tests running on own module one
+has to package the API into one of the official package (or
+link:mailto:dev@netbeans.apache.org[request] his own package to be added into
+the test) and make the module part alpha autoupdate configuration.
+
+Any questions related to the sigtest framework can be either sent to
+link:mailto:dev@netbeans.apache.org[the dev mailing list].
+
+[[Unit_Tests]]
+=== Unit Tests
+
+Very important verification of quality of an API is an automated test suite.
+Most of NetBeans modules uses our test harness called
+link:http://xtest.netbeans.org[xtest] which is based on
+link:http://www.junit.org[JUnit] and enhances it with a few additional features
+(tests should inherit from
+link:https://github.com/apache/netbeans/blob/master/xtest/nbjunit/src/org/netbeans/junit/NbTestCase.java[NbTestCase])
+and configuration framework.
+
+The simplest way how to make your module testable is to copy the `test`
+directory from a small modules that already provide some tests and modify it
+(e.g. link:http://www.netbeans.org/source/browse/html/test/[html]). The needed
+changes include classpath modifications for compilation and execution in
+`build.xml`, correcting the list of tests in `cfg-unit.xml` and of course the
+placing your own tests into `unit/src` directory.
+
+The last step is to include the suite in daily execution of unit tests. For that it is enough to modify the
+link:https://github.com/apache/netbeans/blob/master/xtest/instance/master-config.xml[xtest/instance/master-config.xml] to include your module in the *unit-nb* test config. Verify that you have done everything correctly by running<pre>ant -f nbbuild/build.xml unit-validation</pre>
+
+and checking that your tests were successfully executed. Since then make sure that your module tests really run and pass, as since then other people start to use these tests to verify validity of their own commits. And you should not cause false alarms by problems in your code.
+
+Also consider to subscribe to link:http://beetle.czech:8080/unittest/[notification framework] to get email notifications about automatic failures, if you can reach the URL.
+
+
+[[Deploying_the_APIs]]
+== Deploying the APIs
+
+The important part in a link:API_Design#life.html[life cycle] of an API (as well as any other product) is the feedback from the users. In order to get it one should let your users know that there is an API and allow they to try it. For that purpose NetBeans use its "Alpha Update Center". Curious users may enable it and
+that way be informed about latest development achievements.
+
+To get a module into the "Alpha Update Center" one needs to make sure that the module's `build.xml` file has `netbeans`, `clean`, and `nbm` targets that work in the normal way - normally this is accomplished trivially by making a projectized module and not overriding any targets from the default build harness.Then one can add entries for the new module to `nbbuild/build.properties` in the list `config.modules.daily-alpha-nbms`. Use<pre>
+ant -f nbbuild/build.xml check-module-configs
+cvs diff ide/golden/moduleconfigs.txt
+</pre>to review your changes (check in the new `moduleconfigs.txt` too).
+
+
+One should test the NBM building process on local disk by making sure you have everything of interest checked out from CVS, opening `nbbuild` as a project in the IDE, and selecting *Build Daily Alpha NBMs* from its context menu. If something is messed up, mail gets sent to `broken_builds@netbeans.org` so it can be corrected. It is a good idea to notify
+link:mailto:aumasters@netbeans.org?subject=FYI:%20adding/updating%20daily%20alpha%20NBMs[`aumasters@netbeans.org`] too.
+
+
+[[Publishing_New_Versions]]
+=== Publishing New Versions
+
+The content of "Alpha Update Center" is refreshed every day. The new version of module NBM is build from trunk and specification version in its module manifest is compared to the specification version of already uploaded module. If the new one is greater, the new version of the module replaces the old one.
+
+This means that one can consciously and automatically upload new versions of an API from trunk to its users just by increasing the specification version in the CVS manifest file.
+
+
+[[Stabilize_the_APIs]]
+== Stabilize the APIs
+
+Usually an attempt to produce an API requires longer development time and it is useful to mark it as not being finished yet. NetBeans use a set of link:API_Design.asciidoc#life[stability categories] for that.
+
+The expected scenario is that a module with an API starts its development in a CVS sandbox (link:http://www.netbeans.org/community/contribute/modules.html[contrib.netbeans.org]) or as a regular *netbeans.org* project (like link:http://xml.netbeans.org[xml.netbeans.org]) but is not part of the regular build. Then it is offered on Alpha or Beta AutoUpdate (early access mode) and one can work on its finalization. As the module is not part of a stable release, it can be modified in incompat [...]
+
+
+[[Official_APIs_Restrictions]]
+=== Official APIs Restrictions
+
+There is however one restriction. In order to make it easy for API users to find out what is stable API we have come with a simple description: "If a class is in `org.netbeans.api.*` or `org.netbeans.spi.*` packages, and is part of a stable release, then it is link:API_Design.asciidoc#stable[stable]". Such API is then called NetBeans link:API_Design#official[Official] API.
+
+This rule is not meant to block anyone in producing APIs. One can always create an API in less prominent package (say link:https://bits.netbeans.org/dev/javadoc/#def-api-ant[org.netbeans.modules.ant.api]), publish it on netbeans.org as link:API_Design.asciidoc#stable[stable] one and use all the infrastructure for API development that is available. Moreover this approach is not as strict and allows the API to be part of a release even if it has not reached enough stability for unlimited a [...]
+
+
+[[Support_for_Early_Adoption]]
+=== Support for Early Adoption
+
+There can be situations when strictly following the "official namespace restriction" may cause a lot of troubles to early adopters and hurt NetBeans acceptance and competitiveness. Sometimes one needs to provide an API quickly, cannot guarantee that it is that link:API_Design.asciidoc#stable[stable], but is strongly willing to stabilize it in <em>close future</em>. In such case it may be acceptable to release the API in official packages, mark it as link:API_Design.asciidoc#devel[under d [...]
+
+* the API is intended to become link:API_Design.asciidoc#stable[stable]
+* making it link:API_Design.asciidoc#stable[stable] has been agreed to be the highest priority for next release
+* the API is of "nearly stable" quality - documented, tested, published and successfully reviewed
+
+The purpose of this "temporary release" is to encourage early adopters to test the APIs in real world and provide feedback to make them better. The publishers of the APIs in return promise to stabilize them soon and do that carefully considering the user impact. As a result NetBeans should be able to deliver important APIs as soon as possible, offer them to early adopters and increase API quality by incorporating the feedback. The adopters could be sure that the APIs will be stabilized i [...]
+
+* the javadoc documentation headers shall contain visible warnings
+* the module name shall indicate that it is not stable yet. This shall be done using "/0" in module name, for example `org.netbeans.api.projects.ant/0`. As this string has to be used by every module writer to specify module dependency it forms appropriate warning. When stable version of the module is produced and is incompatible with the "/0" version, the name should change to `org.netbeans.api.projects.ant/2`. If the stable version remains compatible the name of the module should be `or [...]
+
+These suggestions shall ensure that the right balance is achieved between produces and consumers of any NetBeans API. It should however be stated that nobody shall be restricted by "Official namespace restriction" or bound by a time limit of the "temporary release", because if one does not want to create stable API, one does not have to. Contributing to link:API_Design.asciidoc#official[official] API set shall be a privilege as such effort requires more attention and increased amount of [...]
+
+Comments or corrections to link:mailto:dev@netbeans.apache.org[dev@netbeans.apache.org]
+
+[NOTE]
+====
+The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.
+
+This page was exported from link:/wiki.netbeans.org/APIDevelopment[http://wiki.netbeans.org/APIDevelopment] , that was last modified by NetBeans user Jtulach on 2014-01-06T11:46:32Z.
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/APIReviews.asciidoc b/netbeans.apache.org/src/content/wiki/APIReviews.asciidoc
new file mode 100644
index 0000000..e2e193b
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/APIReviews.asciidoc
@@ -0,0 +1,112 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+
+= Purpose of API Reviews
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: Purpose of API Reviews
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+
+The link:API_Design.asciidoc[API] Review is an interactive online process that
+provides architecture review of a feature, change in code or anything else that
+can influence the way link:https://netbeans.apache.org[NetBeans] modules work and behave when
+assembled together to form an application.
+
+The goal of the API Reviews is to supervise the architecture of NetBeans IDE
+and other products based on NetBeans and provide help and suggestions by during
+the reviews. In some way this is a NetBeans way of doing _review before
+integration_. The result of a review can be a suggestion to choose different
+solution, improve the
+link:http://wiki.apidesign.org/wiki/APIDesignPatterns[implementation
+methodologies], link:APIDevelopment.asciidoc#Tests.html[development techniques]
+or link:APIDevelopment.asciidoc#doc.html[documentation].
+
+The goal is to encourage the developers to look at their work from point of
+view of their customers including end users, developers building upon their
+libraries (that is the reason for strong emphasis on
+link:http://wiki.apidesign.org/wiki/Usecase[usecase]s) we apply our knowledge
+gained from maintaining link:https://netbeans.apache.org[NetBeans] for past ten years to make
+the archictecture more sound and more maintainable. The goal usually is not to do
+code reviews. Subject to review are usually aspects visible externally. However
+sometimes a review can suggest better algorithms or internal data structures if
+there are for example link:performance.html[performance] implications.
+
+
+[[How_to_Get_Involved]]
+== How to Get Involved?
+
+The requests for reviews are entered as regular issues into our bug tracking system. They should be marked with keywords *API_REVIEW* or *API_REVIEW_FAST* and that is why it should be easy to query for them. Moreover each review is started by CCing or reassigning the issue to *apireviews@netbeans.org* which automatically sends an email to link:http://netbeans.org/projects/www/lists/api-changes/archive[api-changes@netbeans.org]
+mailing list. That is why subscribe to link:http://netbeans.org/projects/www/lists/api-changes/archive[api-changes@netbeans.org] mailing list or observe *What is currently happening?* query that lists all issues that contain the *API_REVIEW* or *API_REVIEW_FAST* keyword
+and are active, e.g. they were modified during last fourteen days.
+
+The mailing list receives not only before commit notifications but also daily notifications of what is happening in the codebase by using the verification framework. This includes changes in files layout, public packages, link:SignatureTest.html[signatures of various API classes], module dependencies, etc. If you want to get daily notification about the general changes being made, this is the source of information
+you have been looking for as the mailing list allows to observe the current state of the link:NetBeans.html[NetBeans] codebase.
+
+link:https://bz.apache.org/netbeans/buglist.cgi?query_format=advanced&short_desc_type=substring&short_desc=&long_desc_type=substring&long_desc=&bug_file_loc_type=substring&bug_file_loc=&status_whiteboard_type=substring&status_whiteboard=&keywords_type=anywords&keywords=&bug_status=NEW&bug_status=STARTED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailreporter2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=2w&chfieldto=Now&chfieldval [...]
+
+
+[[Reviews_in_Progress]]
+== Reviews in Progress
+
+For each standard review there is an issue describing the problem, linking to appropriated documentation, potentially a review document:
+
+link:https://bz.apache.org/netbeans/buglist.cgi?query_format=advanced&short_desc_type=substring&short_desc=&long_desc_type=substring&long_desc=&bug_file_loc_type=substring&bug_file_loc=&status_whiteboard_type=substring&status_whiteboard=&keywords_type=anywords&keywords=&bug_status=NEW&bug_status=STARTED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailreporter2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue [...]
+
+
+[[Accepted_Reviews]]
+== Accepted Reviews
+
+Accepted reviews, are listed here. Each of the issue contains information about the problem, list of material, set of technical changes requires or advices and a resolution:
+
+link:https://bz.apache.org/netbeans/buglist.cgi?query_format=advanced&short_desc_type=substring&short_desc=&long_desc_type=substring&long_desc=&bug_file_loc_type=substring&bug_file_loc=&status_whiteboard_type=substring&status_whiteboard=&keywords_type=anywords&keywords=API_REVIEW&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&resolution=FIXED&emailassigned_to1=1&emailtype1=substring&email1=&emailreporter2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldf [...]
+
+link:https://bz.apache.org/netbeans/buglist.cgi?query_format=advanced&short_desc_type=substring&short_desc=&long_desc_type=substring&long_desc=&bug_file_loc_type=substring&bug_file_loc=&status_whiteboard_type=substring&status_whiteboard=&keywords_type=anywords&keywords=API_REVIEW_FAST&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&resolution=FIXED&emailassigned_to1=1&emailtype1=substring&email1=&emailreporter2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chf [...]
+
+
+[[Rejected_Reviews]]
+== Rejected Reviews
+
+Rejected reviews were withdrawn or rejected without implementation. Each issue shall contain details describing the motivation and reasons for not implementing it:
+
+link:https://bz.apache.org/netbeans/buglist.cgi?query_format=advanced&short_desc_type=substring&short_desc=&long_desc_type=substring&long_desc=&bug_file_loc_type=substring&bug_file_loc=&status_whiteboard_type=substring&status_whiteboard=&keywords_type=anywords&keywords=&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&resolution=INVALID&resolution=WONTFIX&resolution=WORKSFORME&resolution=INCOMPLETE&emailassigned_to1=1&emailtype1=substring&email1=&emailreporter2=1&emailtype2=subs [...]
+
+
+[[List_of_Suggested_Improvements]]
+== List of Suggested Improvements
+
+* link:http://bz.apache.org/netbeans/buglist.cgi?issue_status=UNCONFIRMED&issue_status=NEW&issue_status=STARTED&issue_status=REOPENED&email1=&emailtype1=substring&emailassigned_to1=1&email2=&emailtype2=substring&emailreporter2=1&issueidtype=include&issue_id=&changedin=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&short_desc=&short_desc_type=substring&long_desc=&long_desc_type=substring&issue_file_loc=& [...]
+* link:http://bz.apache.org/netbeans/buglist.cgi?issue_status=RESOLVED&issue_status=VERIFIED&issue_status=CLOSED&email1=&emailtype1=substring&emailassigned_to1=1&email2=&emailtype2=substring&emailreporter2=1&issueidtype=include&issue_id=&changedin=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&short_desc=&short_desc_type=substring&long_desc=&long_desc_type=substring&issue_file_loc=&issue_file_loc_type=s [...]
+
+[NOTE]
+====
+The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/APIReviews[http://wiki.netbeans.org/APIReviews] , that was last modified by NetBeans user Tomwheeler on 2011-09-14T15:50:05Z.
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/APITest.asciidoc b/netbeans.apache.org/src/content/wiki/APITest.asciidoc
new file mode 100644
index 0000000..da25912
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/APITest.asciidoc
@@ -0,0 +1,47 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+
+= APITest
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:jbake-status: published
+:syntax: true
+:description: APITest SIGTest NetBeans
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+include::SigTest.asciidoc[leveloffset=1]
+
+[NOTE]
+====
+
+The content in this page was kindly donated by Oracle Corp. to the
+Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/APITest[http://wiki.netbeans.org/APITest] ,
+that was last modified by NetBeans user Jtulach
+on 2016-07-15T17:32:32Z.
+
+
+This document was automatically converted to the AsciiDoc format on 2020-03-15, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/API_Design.asciidoc b/netbeans.apache.org/src/content/wiki/API_Design.asciidoc
new file mode 100644
index 0000000..cd71898
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/API_Design.asciidoc
@@ -0,0 +1,791 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+
+= Introduction: How to Design a Module API
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: Introduction: How To Design a (module) API
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+Please visit link:http://wiki.apidesign.org/wiki/Main_Page[apidesign.org] for more information on API Design, and links for the "Practical API Design" book.
+
+A description of good design practices when design any APIs with especially closer look to the case of an API based on NetBeans infrastructure is content of this evolving document.
+
+[[Why_API]]
+== Why API?
+
+The API stands for _Application Programming Inteface_ and before we drill down to descriptions and suggestions how to write it, it is not unreasonable to analyze a bit the meaning of these words.
+
+The word _interface_ indicates that the _API_ lives between at least two different subjects. For example the internal structure of the application could be seen on one side, while leaving foreing applications making calls into it on the on the other. Or there is the programmer (or team) developing the application and its API on one side and on the other the programmers using it. The important observation is that in both cases these two sides are _separated_ - either _compiled_ separatell [...]
+
+It is exactly this _separation_ that implies that rules for designing and maintaining an API. If there was no _separation_ and the whole product was developed by tight team, build at once, there would be no need for bothering with API (as it is definitively more work) and also writing this tutorial. But as the real world *products* are composed from a set of independent *projects* developed by teams that do not necessarily know about each other, have completely different schedules and bu [...]
+
+_Example: _'Linux'_ distributions are done by Mandrake or RedHat, but their content is composed from a thousands of independent open source projects. The producer of the distribution cannot influence their work, it just takes what is available and stable at given time, makes sure that everything works together and creates the release._
+
+
+[[What_is_an_API]]
+== What is an API?
+
+As the reason why API is used is to allow communictation between teams and applications in order to allow separated and distributed development the answer to question what is API shall include everything that influences such kind of development.
+
+_The API is everything that another team or application can depend on_:
+
+* *method and field signatures* - communication between applications is usally about calling functions and passing data structures between each other. If there is a change in the names of the methods, in their arguments or in structure of exchanged data, the whole program often does not even link well, nor it can run.
+* *files and their content* - many applications read various files and their content can influence their behaviour. Imagine application relying on the other one to read its configuration file and modifying its content prior to invoking the application. If the format of the file changes or the file is completely ignored, the communication between those applications gets broken.
+* *environment variables* - for example behaviour of `cvs` can be influenced by the variable `CVSEDITOR`.
+* *protocols* - opening a socket and being prepared to interpret streams sent there, or putting or reading a data to clipboard or during drag and drop again establishes an API that others can depend on.
+* *behaviour* - a bit harder to grip, but important for the separation as well is the the dynamic behaviour. How the program flow looks like - what is the order of execution, what locks are being held during calls, in which threads a call can happen, etc.
+* *L10N messages* - because the localization to a certain language is usually developed and distributed by somebody other than the person that writes the code, yet both of them have to use the same keys (`NbBundle.getMessage ("CTL_SomeKey")`), there is inherently a contract between the writer of the code and the translator - an API of sorts.
+
+The important thing with respect to distributed development is to be aware of possible APIs - of possible things other code can depend on. Only by identifying such aspects of own application one can develop it in a way that will not hurt cooperation with seperately developed applications.
+
+
+[[The_Importance_of_Being_Use_Case_Oriented]]
+== The Importance of Being Use Case Oriented
+
+It is often not hard to decide whether a program is good or bad - if it crashes without doing anything useful, it is bad. If the program cannot compile, it is even worse. But if it runs, helps to get a work done, just sometimes crashes, it is hardly good, but also it does not need to completely bad. The decision depends on the perception of the evaluator. The _subjective feeling_ does matter. And the same applies when one tries to judge a design. It does not matter whether it is a UI des [...]
+
+On the other hand software engineering is (or at least should be) done by engineers and important part of engineering is its measurability. So the ultimate goal for reasoning about design is to make it measurable, to suppress the subjective opinions and define set of requirements that will be used to measure the quality of the design. Of course defining the requirements might need some personal opinions, but as soon as they are written down, one can become pure engineer and use pure scie [...]
+
+But as shown on the example of a good/bad program, the users _subjective feeling_ is important. And it is important in design as well. But in case of _API_, which stands for the interface between the internals of an application and a programatic usage of its functionality, the person that will have the _subjective feeling_ is the programmer using the _API_. He is the _API_ user. He is the one that will judge the design and represent opinions whether it is good or bad. Of course, such opi [...]
+
+The external programmer is more concerned by the time needed to learn the API, by the amount of code needed to get his tasks done and by the stability of the contract. The art of making good API lays exactly in meeting these opposite requirements.
+
+As usually one shall optimize for larger audience, for bigger effect. Usually the amount of people using an API is a way larger than those coding it, and that is why one shall take a special care to simplify the life of these users. Little uneasiness in implementing the application is acceptable, if the life of majority of users is simpler. To better address user needs it is necessary to know and understand their requirements. If an API allows easy implementation of the common tasks, it [...]
+
+That is why the initial step in API design is to investigate and collect the scenarios for possible uses of the application. Having these use cases written down allows evaluation of each aspect of the API and validation of the design. The use cases serve as a fixed point to which one validates the design of API. It is practically impossible to jugde the quality of a design, but it is relatively easy to check whether the design satisfies required use cases or not.
+
+Once a usecase becomes supported, it should stay supported until the end of the world (e. g. until it is not interesting anymore).
+
+
+[[Life-cycle_of_an_API]]
+== Life-cycle of an API
+
+There seems to be two ways a feature can become an _API_ (defining _API_ as a stable interface that others can use over time without unpleasant surprises). An _API_ can be evolved
+
+* *spontaneously* - someone is developing a feature, and another person finds it useful and starts to use it. Later they find out about each other, share their experiences and very likely find that the original design of the feature is not general enough or that it was never intended to be treated as an _API_ In order to evolve it toward being an _API_ they discuss changes to make the feature better and after few iterations it can become a useful and stable contract.
+* *by design* - there is a known need for a contract between two components of the system. The requirements are collected, the problem area investigated, the use cases understood, and then someone designs and writes the _API_. Now others can use it in real world, comment, file bugs and enhancements which results in improvements to the _API_ and finally evolve it into a state where it is a useful and stable contract.
+
+In spite that these cases start differently they share the same attributes: Both of them need some time for feedback and evaluation before the _API_ can be known to work and suit its purpose. Not every effort ends as its life as a stable API; sometimes it may turn out that the chosen way leads nowhere and then it is better to abandon the work.
+
+include::API_Stability.asciidoc[leveloffset=2]
+
+At the beginning of this chapter two different ways have been mentioned how an
+API can be developed. Doing that *spontaneously* means in the light of the
+above link:API_Stability.asciidoc[API Stability] categories to introduce a
+_private_ or _friend_ link:API_Design.asciidoc[API], that is discovered by
+someone else, found useful and than evolves into _stable_ one as described. An
+link:API_Design.asciidoc[API] developed by design is more likely to begin its
+life with _under development_ link:API_Stability.asciidoc[API Stability] status
+and after a bit of work can turn into _stable_ API.
+
+
+[[Preservation_of_Investments]]
+== Preservation of Investments
+
+One of the most important things for NetBeans is fair treatment of our partners. Module authors, platform extenders, contributors and others have to be sure that their work will not vanish or break whenever a new release of NetBeans is announced. Their work has a right to be respected and admired. As long as NetBeans succeeds at that we can be sure that our partners will describe their experience to others and evangelize and evolve the NetBeans community.
+
+Because different parts of the system communicate with each other using public contracts (API, SPI, registration places, defined functional behavior), the way to preserve participants' investments is to always evolve these contracts in compatible ways. Each new version of NetBeans should make sure that it allows existing modules to execute and work in reasonable way, or, failing that, that it is easy to update existing sources to compile and use the contracts of the new release.
+
+
+[[Maintained_.26amp.3B_unmaintained]]
+=== Maintained & unmaintained
+
+Another reason why it is necessary that previous versions of modules continue to work is that often there is a module that works well and does an excellent job for its users, but in reality it is unmaintained. This can happen because the owner has left, works on different project or the company that created it does not exist anymore. There are even some projects on netbeans.org which are unmaintain but still serving their users well. If a new NetBeans version is released and introduces s [...]
+
+On the other hand, the owner may still be alive, and want to bring their code up to date - for example, one of the reasons for changes to APIs is to improve performance, something any module author would want to take advantage of. This should be easy to do, requiring no work in most cases. However, even if great attention is paid to evolving the APIs well, in some cases updating may require a bit of work. If someone is maintaining a module, they are expected to make the necessary updates [...]
+
+
+[[Examples]]
+=== Examples
+
+Even the biggest currently known change of behavior (the classpath change planned for 4.0) still allows a user to use a module developed against previous version of NetBeans and correctly use its functionality. If someone wants to use an old module, the only necessary thing is to setup the roots of filesystems to match the classpath.
+
+On the other hand, APIs are designed by human beings, and the best of APIs may still contain things that turn out later to be mistakes. One example of such a mistake is the Node.Cookie marker interface, which restricts the usability of Cookies and forces a dependency on the nodes package that is not strictly necessary. This interface should be removed. As such the Node.Cookie Node.getCookie (Class) method will be changed to Object Node.getCookie (Class). Even after the change it can be g [...]
+
+[source,java,subs="{markup-in-source}"]
+----
+MyCookie c = (MyCookie)node.getCookie(MyCookie.class);
+----
+
+The remaining 1% of uses, which look like:
+
+[source,java,subs="{markup-in-source}"]
+----
+Node.Cookie c = node.getCookie(something);
+----
+
+will have to be updated, but active module authors will do it gladly because they profit by having their classes become more flexible, and the change that must be done is very simple. Of course instruction for doing this update has to be prominent part of release migration guide.
+
+
+[[Design_Practices]]
+== Design Practices
+
+Let's talk about actual Java design practices and patterns that help the writer and maintainer to achieve the general suggestions and rules that have been discussed in previous chapters and the make the user of an API feel comfortable, unsurprised and happy.
+
+
+[[Do_not_expose_more_than_you_want]]
+=== Do not expose more than you want
+
+Obviously the less of the implementation is expressed in the API, the more flexibility one can have in future. There are some tricks that one can use to hide the implementation, but still deliver the desired functionality. This section will discuss some of such tricks.
+
+
+[[Method_is_better_than_Field]]
+==== Method is better than Field
+
+It is better to use methods (usually getters and setters) to access fields than to expose them directly. The first reason is that a call to a method can do a lot of additional things, but in contrast an access to a field can only read or write the value. When using getters one can for example do lazy initialization, synchronize the access or compose the value using some computation algorithm. Setters on the other hand allow checks for correctness of assigned value or notification of list [...]
+
+The other reason why to prefer methods can be found in the _Java Virtual Machine_ specification. It is allowed to move a method from a class to one of its superclasses and still remain binary compatible. So a method initially introduced as `Dimension javax.swing.JComponent.getPreferredSize(Dimension d)` can be deleted in new version and moved to `Dimension java.awt.Component.getPreferredSize(Dimension d)` as the `JComponent` is a subclass of `Component` (this really happened in JDK 1.2). [...]
+
+
+[[Factory_is_better_than_Constructor]]
+==== Factory is better than Constructor
+
+It is more flexible to expose a factory method than to expose constructor. Once a constructor is available as part of an API, it guarantees not only that an instance assignable to a given class will be created, but also that the instance will be of the *exact class* (no subclasses allowed) and also that a *new instance* is created every time.
+
+If instead a factory method is provided (usually a static method that takes the same arguments as the constructor and returns instance of the same class the constructor is defined in), one has more possibilities. First of all one does not need to return the exact class, but some subclass - allows to use polymophism and possibly clean up the code. Second avantage is to cache instances. While in case of constructor new instance is created every time, the factory method can cache previously [...]
+
+
+[[Make_Everything_Final]]
+==== Make Everything Final
+
+In a lot of cases people are not designing for subclassing and still they do
+not prevent it. If you are writing an API and you explicitly do not want people
+to subclass or implement your interfaces (also see paragraph about
+[#design.apiandspi API vs. SPI]) it is better to disallow that.
+
+Simplest solution is to make your class `final`. Other tricks include non-public constructors (one shall do it anyway in favor of [#design.less.factory factory methods]) or making all (or at least most) methods `final` or `private`.
+
+Of course this works only for classes, if you decide to use interfaces you cannot forbid foreign implementations on the level of virtual machine, you can only ask people in JavaDoc not to do it.
+
+
+[[Allow_access_only_from_a_friend_code]]
+==== Allow access only from a friend code
+
+Another useful technique to not expose too much in API is to give access to certain functionality (e. g. ability to instantiate a class or to call a certain method) just to a friend code.
+
+Java by default restricts the friends of a class to those classes that are in the same package. If there is a functionality that you want share just among classes in the same package, use _package-private_ modifier in definition of a constructor, a field or a method and then it will remain accessible only to friends.
+
+Sometimes however it is more useful to extend the set of friends to a wider
+range of classes - for example one wants to define a pure API package and put
+the implementation into separate one. In such cases following trick can be
+found useful. Imagine there is a class item (btw. also you can also check out
+link:http://treefs.netbeans.org/source/browse/treefs/apidesign/friendpackage/[sources
+from CVS]):
+
+[source,java,subs="{markup-in-source}"]
+----
+
+public final class api.Item {
+ /** Friend only constructor */
+ Item(int value) {
+ this.value = value;
+ }
+
+ /** API method(s) */
+ public int getValue() {
+ return value;
+ }
+
+ /** Friend only method */
+ final void addListener(Listener l) {
+ // some impl
+ }
+}
+----
+
+that is part of the API, but cannot be instanitated nor listened on outside of the friend classes (but these classes are not only in api package). Then one can define an `Accessor` in the non-API package:
+
+[source,java,subs="{markup-in-source}"]
+----
+public abstract class impl.Accessor {
+ public static Accessor DEFAULT;
+
+ public static Accessor getDefault() {
+ if (DEFAULT != null) {
+ return DEFAULT;
+ }
+
+ // invokes static initializer of Item.class
+ // that will assign value to the DEFAULT field above
+ Class c = api.Item.class;
+ try {
+ Class.forName(c.getName(), true, c.getClassLoader());
+ } catch (ClassNotFoundException ex) {
+ assert false : ex;
+ }
+ assert DEFAULT != null : "The DEFAULT field must be initialized";
+ return DEFAULT;
+ }
+
+ /** Accessor to constructor */
+ public abstract Item newItem(int value);
+ /** Accessor to listener */
+ public abstract void addListener(Item item, Listener l);
+}
+----
+
+with abstract methods to access all friend functionality of the `Item` class and with a static field to get the accessor's instance. The main trick is to implement the `Accessor` by a (non-public) class in the `api` package:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+final class api.AccessorImpl extends impl.Accessor {
+ public Item newItem(int value) {
+ return new Item(value);
+ }
+ public void addListener(Item item, Listener l) {
+ item.addListener(l);
+ }
+}
+----
+
+and register it as the default instance first time somebody touches `api.Item` by adding a static initializer to the `Item` class:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+public final class Item {
+ static {
+ impl.Accessor.DEFAULT = new api.AccessorImpl();
+ }
+
+ // the rest of the Item class as shown above
+}
+----
+
+Then the _friend_ code can use the accessor to invoke the hidden functionality from any package:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+api.Item item = impl.Accessor.getDefault().newItem(10);
+impl.Accessor.getDefault().addListener(item, this);
+----
+
+Please note that in _NetBeans_ this is very useful in combination with specifying publicly accessible packages in module manifest (`OpenIDE-Module-Public-Packages: api.**`) and thus disallowing on the class loading level other modules from accessing the `impl.Accessor`.
+
+
+[[Separate_API_for_clients_from_support_API]]
+=== Separate API for clients from support API
+
+Are there really more types of API? If so, how do they differ? Do the users of those types differ? Do they have different expectations? Those are questions that shall be answered in the first part of this section. Then we will try to define the restrictions on evolution of different types of API, and present some tips, tricks and lessons learned, which one can use to achieve and enforce such restrictions.
+
+
+[[The_Client_vs._Provider_API]]
+==== The Client vs. Provider API
+
+Before we start, we should ask a question: Who is the client and who is the provider? Let us do it on an example of _XMMS_, the media player for _UNIX_es (called WinAmp on another platform).
+
+The player can play audio files, can skip to next song, return to previous one, offers a playlist with possibility to add, remove and reorder songs. The functionality is provided for users, but accessible to other programs as well. So a program can call `xmms.pause()` or `xmms.addToPlaylist(filename)`. As can be seen, the communication is initiated by the other program that uses the player's API to instruct it to perform an action. After the execution of the command ends, the control ret [...]
+
+On the other hand, the _XMMS_' APIs also allows third parties to register _output plugin_s. The functionality of the default player can be extended by providing a utility method that writes the played data to a disk, broadcasts it over a network, etc. The communication is in this case initiated by the player itself. After collecting enough data for playback, the program locates the current output plugin and sends it the data to process: `plugin.playback (data)`. After finishing the playb [...]
+
+
+[[Expressing_API.2FSPI_in_C_and_Java]]
+==== Expressing API/SPI in C and Java
+
+In this section we will discuss the actual implementation of the API in two sample languages - procedural C and object oriented Java.
+
+The C language is ready and suitable for expressing (client) API. One just writes the methods and announces them in the header files, so others can compile agaist them:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+void xmms_pause();
+void xmms_add_to_playlist(char *file);
+----
+
+The Java way is not much different:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+class XMMS {
+ public void pause();
+ public void addToPlaylist(String file);
+}
+----
+
+but one has more choices. It is possible to declare these methods static, to leave them as instance methods, make them abstract, final, etc. But generally speaking, the way C and Java handle client APIs is nearly similar. However the situation is a far different when writing an SPI.
+
+In order to write own plugin for _XMMS_ in C one has to start with a method that will do the playback. So the a plugin must define:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+void my_playback(char *data) {
+ // do the playback
+}
+----
+
+and the player itself has to have some registration method, for example,
+
+[source,java,subs="{markup-in-source}"]
+----
+
+void xmms_register_playback((void)(f*)(char*));
+----
+
+that the plugin should call to register itself. ` xmms_register_playback(my_playback)` and its playback function is then called by the _XMMS_ whenever necessary. In Java the contract starts with a definition of playback interface:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+interface XMMS.Playback {
+ public void playback(byte[] data);
+}
+----
+
+then my plugin has to implement that interface `MyPlayback implements XMMS.Playback` and register that instance to the player:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+XMMS.registerPlayback(new MyPlayback());
+----
+
+and that is all. The player can do its calls to the plugin as it could in case of C. The major difference is that writing this kind of code is taught in Java courses without a proper explanation of what it really means.
+
+In the C case, the amount of work to produce an SPI (for example callback) is high enough to prevent beginner from even trying it. One's knowledge has to grow significantly to get to state when one can (or will need to) design an SPI. But in Java any declared method that is not private, final or static is defacto an invitation for someone to provide a callback and thus an accidental SPI. This is often not well understood by programmers, teachers, and is not part of conventional wisdom. A [...]
+
+
+[[Evolution_of_API_is_a_different_process_than_evolution_of_SPI]]
+==== Evolution of API is a different process than evolution of SPI
+
+Evolution is a natural part of any contract. After a time everything gets obsoleted, insufficient or broken. APIs and SPIs are not exceptions. So it is better be prepared for evolution at the begining, plan for it and avoid mistakes that would otherwise be hard to undo.
+
+In case of an API that is offering methods to clients, there is no problem with additions. Extending the functionality to offer more functionality to clients cannot hurt them - if they do not want they do not need to use it.
+
+In the cas of an SPI, the situation is exactly the oposite. Adding new method into an interface that others must provide effectively breaks all existing implementations, because they do not implement it! On the other hand it acceptable and valid to stop calling (de facto removal) a method from an SPI. If the operation flow is not part of the contract, not calling one method should not break anything.
+
+So the way of evolution depends on the type of the interface: API additions are fine but removing functionality is not; SPI de-facto removals are allowed, but additions are not. At the begining of producing a contract, one should realize and understand which parts will be API that clients will call, and what will be SPI that will extend the functionality one is writing. The biggest mistake that one can make is to _mix API and SPI together_ into one class. Then there is no room for evolut [...]
+
+
+[[Example]]
+==== Example
+
+As an example let us choose `DataObject` class, a part of the
+link:https://bits.netbeans.org/dev/javadoc/org-openide-loaders/org/openide/loaders/DataObject.html[Data
+System API]. It is used for by clients to obtain a logical, representation of a
+file or set of files, and logically manipulate their contents:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+// locate a data object
+DataObject obj = DataObject.find(fo);
+// move it to different place
+obj.move(destination);
+// try to open it if supported
+OpenCookie o = (OpenCookie)obj.getCookie(OpenCookie.class);
+if (o != null) {
+ o.open();
+}
+----
+
+But the problem is that this client API is mixed together with a lot of methods
+provided just for subclasses (those that are protected in
+link:https://bits.netbeans.org/dev/javadoc/org-openide-loaders/org/openide/loaders/DataObject.html[javadoc]).
+They pointlessly clutter the API and moreover prevent the API from being
+extended in future. Moreover not only do the API and SPI conflict and make
+evolution difficult, but the execution flow between API and SPI resulted in a
+lot of flow clashes - deadlocks.
+
+That is why during design of
+link:http://openide.netbeans.org/proposals/loaders/[new data systems] the
+`DataObject` has been reserved just for the API. It is supposed to be final and
+fully controlled by the implementation. The actual behaviour is provided by a
+separate SPI:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+interface DataObjectOperator {
+ // delegated to from DataObject.move(DataFolder df)
+ public void move(DataObject obj, DataFolder target);
+ // delegated to from DataObject.rename(String name)
+ public void rename(DataObject obj, String name);
+ // delegated to from DataObject.getCookie(Class clazz)
+ public Object getCookie(DataObject obj, Class clazz);
+ // etc.
+}
+----
+
+By separating the API from SPI and fully controlling the flow between them we can evolve the API and SPI independently and moreover add various pre-condition and post-condition checks between the actual client and provider. For example it is simple to add a new method `DataObject.move(DataFolder df, String newName)` to the API that should move the object and rename it at once and bridge it as `move` and `rename` calls into the `DataObjectOperator` by default and (in case of of new improv [...]
+
+The new data systems should be an example of good design that is aware that _what's good for SPI implementors isn't necessarily good for API clients_, tries to give the API a chance to evolve and also _restrict SPI implementors as little as possible_.
+
+Another example in case you are not yet convinced:
+link:https://bits.netbeans.org/dev/javadoc/org-netbeans-modules-project-ant/org/netbeans/api/project/ant/AntArtifact.html[AntArtifact]
+was originally made an abstract class, rather than an interface, so that some
+final methods like `getArtifactFile` and `getScriptFile` could be added for
+clients, and `getID` could be defaulted. It seemed reasonable at the time. Of
+course, it turned out that later the SPI part had to be extended to support
+multiple artifacts and properties. Adding support for properties was easy
+enough to do compatibly, but adding support for multiple artifacts was messier:
+we had to deprecate the old single-artifact getters and introduce new getters,
+while preserving compatibility for old implementations. It would have been
+simpler to do had there been a final class `AntArtifact` with a factory method
+accepting an SPI interface `AntArtifactImpl` (or the like), since we could have
+produced a new SPI interface and a new factory method.
+
+
+[[Interfaces_vs._abstract_classes]]
+=== Interfaces vs. abstract classes
+
+There seems to be long, never-ending flame war between those who prefer the strict use of interfaces and those who like abstract classes. Such discussions continue forever, starting usually every few months again and leading nowhere, because people tend to hold to their opinions. Often such discussions start with no common ground - no agreement on use cases or requirements. Below we will look at the problem from use case point of view.
+
+
+[[The_Advantages_of_Interfaces]]
+==== The Advantages of Interfaces
+
+The most obvious one is that _usage of the type_, if implemented as an abstract class, is limited as java doesn't allow multiple inheritance of classes. This only becomes a problem when a type is huge, or when it significantly enhances developer productivity to be able to subclass and reuse a base implementations. We will call these _support classes_, where one is expected to subclass and reuse a base class's implementation.
+
+The second advantage of interfaces is that there is an _enforced separation between the API and the implementation_. But this can be achieved with abstract classes too, with a bit of self control, while in interfaces that is enforced by the compiler.
+
+
+[[The_Advantages_of_Abstract_Classes]]
+==== The Advantages of Abstract Classes
+
+The main reason why people prefer to use abstract classes is their _ability to evolve in a time_ - it is possible to add a new method with a default implementation without breaking existing clients or implementors (here we talk about runtime compatibility, not compile time one). Interfaces lack such functionality, so it is necessary to introduce another interface to provide future extensions. So you end up with a lot of interfaces such as `interface BuildTargetDependencyEx extends BuildT [...]
+
+A second very useful feature of abstract classes is the possibility of _restricting access rights_. Every method in a public interface is public and everybody can implement the interface. That for example means anybody can implement such interface, but in real life, one often wants to restrict that and have the creation under control. Interfaces lack such restrictions.
+
+Another thing that is possible with abstract classes is that they can contain static methods. Of course that with interface one can create separate classes with factory methods, but the truth is that a class is usually the most natural and reasonable place for factory methods that return instances.
+
+
+[[Use_cases]]
+=== Use cases
+
+Let's now give few real world examples and discuss whether the use of one or the other approach has some benefits and why.
+
+
+[[TopManager]]
+==== TopManager
+
+The link:https://github.com/apache/netbeans/tree/master/platform/openide/src/org/openide/TopManager.java?content-type=text/plain[ TopManager ] is one of the oldest types in the NetBeans Open APIs and was designed to bridge between the `org.openide.*` packages and their implementation in `org.netbeans.core`. There is just one instance of the manager (provided by the core) and clients of the API are not at all expected to extend/implement that type.
+
+Analysis shows that this is a typical situation of providing a lot of utility
+methods to clients with complete control over the implementation, where
+attention is be paid to ease of use for clients of such API, while permitting
+dynamic discovery of the implementation (the API is in different compilation
+unit [openide] than its implementation [core]).
+
+This is a situation where one cannot gain any advantage by using interfaces
+over using abstract classes. One needs a factory method, one can add new
+methods, separation between API and implementation is in the right hands and
+there is also the possibility to prevent instantiation of other instances than
+the default one. If you happen to be in similar situation, it is best to use an
+abstract class.
+
+An example what can happen if one chooses to use an interface is located next
+to `TopManager` in the same package - the
+link:https://github.com/apache/netbeans/tree/master/platform//openide/src/org/openide/Places.java?content-type=text/plain[
+Places ] interface. In reality it is the same singleton as the `TopManager`, it
+is accessed via the factory method `TopManager.getDefault().getPlaces()`. All
+its methods could be part of the `TopManager` as well. We just wanted to
+logically separate them and we did it using an interface. As a result, as newer
+"places" that might be useful API were created, we were afraid to add a method
+there after a time. Since we decided creating a `Places2` interface would be
+overkill, the interface started to be less and less used and now is nearly
+obsolete.
+
+
+[[Cookies]]
+==== Cookies
+
+The link:http://www.netbeans.org/source/browse/openide/src/org/openide/cookies/[ cookies ] are a coding pattern that allows any object to provide a specific feature (called cookie) by calling:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+OpenCookie openCookie = (OpenCookie)anObject.getCookie(OpenCookie.class);
+if (openCookie != null) {
+ openCookie.open();
+}
+----
+
+Should the `OpenCookie` be interface or abstract class? Simple analysis can show that there is a lot of clients, users of the API, and also a lot of providers, often wanting to provide more cookies at once. Moreover the cookie itself contains just one method `open`. All of the that leads to answer that the type should be an interface. We have the ability for multiple inheritance, and there is no fear of evolving the interface because it has just one method that does it all, no need for s [...]
+
+Very similar, but also very different example can be shown on another cookie - the link:https://github.com/apache/netbeans/tree/master/platform//openide/src/org/openide/cookies/InstanceCookie.java?content-type=text/plain[ InstanceCookie ]. It is also an interface and it used to have three methods but after few releases we realized a need for another to improve performance. So we were forced to introduced a subclass `InstanceCookie.Of` extending `InstanceCookie` and adding method `instanc [...]
+
+[source,java,subs="{markup-in-source}"]
+----
+
+boolean doIAccept;
+InstanceCookie ic = (InstanceCookie)obj.getCookie(InstanceCookie.class);
+if (ic instanceof InstanceCookie.Of) {
+ doIAccept = ((InstanceCookie.Of)ic).instanceOf(myRequiredClass);
+} else {
+ doIAccept = ic != null &&
+ myRequiredClass.isAssignableFrom(ic.instanceClass());
+}
+----
+
+The code is not too simple and moreover is spread over the whole codebase. How much simpler it would be if we could just add a new method into the cookie:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+boolean isInstanceOf(Class c) {
+ return c.isAssignableFrom(instanceClass());
+}
+----
+
+but because java does not allow default methods in interfaces, we are out of luck. Should we have used abstract class? No, we should not, the use cases are similar as with `OpenCookie`, but there is another trick that (very likely) should have been used.
+
+Instead of adding three methods into the interface we could add just one that would return a class with all necessary information.
+
+[source,java,subs="{markup-in-source}"]
+----
+
+interface InstanceCookie {
+ public Info instanceInfo();
+
+ public static class Info extends Object {
+ public String intanceName();
+ public Class instanceClass();
+ public Object instanceCreate();
+ }
+}
+----
+
+This solution seems to combine the best of both worlds. Clients have simple API, providers can implement instead of extend and in the `instanceInfo` method instantiate the info either with some provided constructor or factory methods or lazily using subclassing. Also when we need to add the `instanceOf` after few releases, we can. `InstanceCookie.Info` is a class and as such can be extended by a method with a default implementation.
+
+Of course to make such methods additions safe, it is better to make the class final and provide factory methods that implementors of `InstanceCookie` could use. Those factory methods could either be simple, e.g. take values for `instanceName`, `instanceClass` and `instanceCreate` methods. Or the factory methods could take another interface with a methods that would be called to lazily handle the invocations of for example `Info.instanceCreate`. The actual solution depends on the needs of [...]
+
+Please notice that similar pattern is used by java listeners. Every listener is an interface and as such it has a constant (often one) number of methods. But each method takes a subclass of link:https://docs.oracle.com/javase/1.4/docs/api/java/util/EventObject.html[EventObject] which is a class and if necessary can be enhanced with a link:https://docs.oracle.com/javase/1.4/docs/api/java/awt/dnd/DragGestureEvent.html#startDrag(java.awt.Cursor,[java.awt.datatransfer.Transferable) new method].
+
+
+[[FileObject]]
+==== FileObject
+
+Another example from NetBeans is the link:https://github.com/apache/netbeans/tree/master/platform//openide/src/org/openide/filesystems/FileObject.java?content-type=text/plain[ FileObject ] (part of the link:https://bits.netbeans.org/dev/javadocorg-openide-filesystems/org/openide/filesystems/doc-files/api.html[filesystem API]). This type usage seems very close to the TopManager example (but is not as obvious): There are very few people directly subclassing `FileObject` (javadoc's HttpFile [...]
+
+The amount of people directly subclassing link:https://github.com/apache/netbeans/tree/master/platform//openide/src/org/openide/filesystems/FileSystem.java?content-type=text/plain[ FileSystem ] is the same as those doing that for `FileObject`, so it seems fine to choose abstract class for both types, but it is true that the filesystem would probably work as interface too.
+
+Moreover there is a support class, the link:https://github.com/apache/netbeans/tree/master/platform//openide/src/org/openide/filesystems/AbstractFileSystem.java?content-type=text/plain[ AbstractFileSystem ] that most of the people providing filesystem implementations are subclass. Because it is a support class, it needs to be a concrete class or at least a factory method, but it offers five interfaces (Info, Change, Attr, List, Transfer) that are not exposed in the client API for users o [...]
+
+
+[[CloneableEditorSupport]]
+==== CloneableEditorSupport
+
+Can support link:https://github.com/apache/netbeans/tree/master/platform//openide/src/org/openide/text/CloneableEditorSupport.java?content-type=text/plain[ class]es be provided as interfaces? It is not easy. What kind of support would it be if one would have to provide implementation of each method! So, often abstract classes are used as base for support classes.
+
+But one should carefully separate the support classes from the actual API (as the `CloneableEditorSupport` is in different package than the link:https://github.com/apache/netbeans/tree/master/platform//openide/src/org/openide/cookies/EditorCookie.java?content-type=text/plain[ EditorCookie ] which it implements). Such separation ensures basic quality of design and prevents cheating - one needs to use just API methods even in the implementation and cannot rely on non-public hooks.
+
+
+[[Interfaces_or_Classes]]
+=== Interfaces or Classes?
+
+Is it better to use interfaces or a classes? None, could be simple answer to such general question. But if try to get down to the roots of the question we can get a better answers.
+
+First of all only those people that are designing an API that will be maintained for a while, have to care. Those who are writing code to pass an exam do not need to. They can choose whatever they wish.
+
+Second necessary thing is to treat users of your API well. If you do not care about them, do not care about the _interfaces or classes_ question.
+
+If these conditions are satisfied then, from the discussion above, one can see that classes are better for _client API_ and interfaces for _service provider API_. So if you know that most of the users of an API will just make calls to it, it is better to use classes (and the best thing is to make them unsubclassable, that way one prevents accidental subclasses at all). If you want people just to subclass. Then choose interfaces, they are more safe and easy to use when subclassing. If you [...]
+
+
+[[Case_Study_of_client_API_and_SPI_separation]]
+== Case Study of client API and SPI separation
+
+The previous example with `CloneableEditorSupport` claims that it is not easy to write support without classes, but the truth is it is not that complicated and moreover it really separates the SPI from the client API and allows easier and safe future evolution. Here is a sample rewrite of `CloneableEditorSupport` stuff using interfaces:
+
+The main goal of link:http://www.netbeans.org/source/browse/openide/src/org/openide/text/CloneableEditorSupport.java?rev=1.92&content-type=text/x-cvsweb-markup&showattic=1[CloneableEditorSupport] is to implement some interfaces link:http://www.netbeans.org/source/browse/openide/src/org/openide/cookies/OpenCookie.java?rev=1.7&content-type=text/x-cvsweb-markup&showattic=1[OpenCookie], link:http://www.netbeans.org/source/browse/openide/src/org/openide/cookies/EditCookie.java?rev=1.6&content [...]
+
+
+[[Move_Protected_Methods_Into_Interface]]
+=== Move Protected Methods Into Interface
+
+The situation might be simplified by separating all methods that should be overriden in subclasses into own interface:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+public interface CloneableEditorProvider {
+ // methods that have to be overridden
+ // in order for the functionality to work
+ public String messageName();
+ public String messageSave();
+
+ // additional stuff described below
+}
+----
+
+and having a factory method
+
+[source,java,subs="{markup-in-source}"]
+----
+
+EditorCookie EditorFactory.createEditor(CloneableEditorProvider p);
+----
+
+that would convert the service provider interface into the desired client API (this is a bit simplified, the real API would have to support creation of multiple cookies `OpenCookie`, `EditCookie`, etc. for example by having additional argument of type `Class[]` that would specify all cookies the returned value should implement). Functionally this is equivalent to providing a class with abstract methods that should be implemented in subclasses, however in addition, it guarantees that nobo [...]
+
+
+[[Passing_Notifications_to_Implementation]]
+=== Passing Notifications to Implementation
+
+But the current state does not yet fully emulate the functionality of the old `CloneableEditorSupport` - the provider is not able to invoke `reloadDocument` or any similar one. In order to address this, let's enhance the interface:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+public interface CloneableEditorProvider {
+ // the getter methods as in previous example
+ public String messageSave();
+
+ // the support for listeners
+ public void addChangeListener(ChangeListener l)
+ throws TooManyListenersException;
+ public void removeChangeListener(ChangeListener l);
+}
+----
+
+Now the factory methods will not just build an implementation of `EditorCookie`, but will also attach such implementation as a listener to the provider. As there will always be at most one listener, the method signagure throws `TooManyListenersException` to signal that the provider can implement the method in the most simple way:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+private ChangeListener listener;
+public void addChangeListener(ChangeListener l)
+ throws TooManyListenersException {
+ if (listener != null) throw new TooManyListenersException();
+ listener = l;
+}
+----
+
+and does not need to bother with support for multiple listeners, while following the *JavaBeans* conventions. Whenever the provider needs to reload the document, it can just fire `listener.stateChanged (ev)` and the listening implementation will know that the reload of the document is requested.
+
+
+[[Callbacks_to_Implementation]]
+=== Callbacks to Implementation
+
+The listener approach allows simple communication flow from the provider to the implementation when needed, but there is still something missing - ability to obtain `UndoRedo` via `CloneableEditorSupport.getUndoRedo`. In order to achieve that we might change the interface once more:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+public interface CloneableEditorProvider {
+ // the getter methods as in previous example
+ public String messageSave();
+
+ // the support callbacks
+ public void attach(Impl impl) throws TooManyListenersException;
+
+ // the class with methods for communication with the implementation
+ public static final class Impl extends Object {
+ public void reloadDocument();
+ public UndoRedo getUndoRedo();
+ }
+}
+----
+
+We have replaced the listener with a special `Info` that contains all the methods that the provider can call on the implementation and added a method `attach` to allow registration of that class to any provider.
+
+This is the final state. Everything that is supposed to be called from the implementation is in the `CloneableEditorProvider` interface, everything that is supposed to be called by a clients is not avaible as `EditorCookie` and is completelly under control of the `EditorFactory` and the callback communication from the provider to the factory is separated into the `CloneableEditorProvider.Impl`. This state can at first sight look more complex than the original `CloneableEditorSupport`, bu [...]
+
+
+[[Extensible_Client_Behaviour]]
+=== Extensible Client Behaviour
+
+Anybody wants to add new user method or functionality into `EditorCookie`? Why not, just enhance the `EditorFactory` to create better implementation in its factory method. Is there a need to log requests from clients? Again, `EditorFactory` is the right place to do it. Necessary to provide some synchronization, deadlock prevention, etc? Where else then in `EditorFactory`.
+
+
+[[Extensible_Communication_betwen_provider_and_implementation]]
+=== Extensible Communication betwen provider and implementation
+
+As we have carefully choosen the `CloneableEditorProvider.Impl` to be final class, we can always add a new methods to it. For example:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+public static final class CloneableEditorProvider.Impl extends Object {
+ public void reloadDocument();
+ public UndoRedo getUndoRedo();
+ public void closeDocument();
+}
+----
+
+as far as we teach the implementation to understand what `closeDocument` means. Btw. actually the `Impl` acts as a client API for the `CloneableEditorProvider` and that is why it is better to make it class.
+
+
+[[Extensible_Provider_Evolution]]
+=== Extensible Provider Evolution
+
+It is often common that after a while the functionality of the `EditorCookie` might be improved, if the `CloneableEditorProvider` was a bit more capable. In the original `CloneableEditorSupport` example this would be solved by adding new (protected) method with default implementation in the `CloneableEditorSupport`, but as adding a method is always a bit dangerous (might introduce clashes - what used to compile in previous version need not compile anymore, or need not run anymore). The p [...]
+
+[source,java,subs="{markup-in-source}"]
+----
+
+interface CloneableEditorProvider2 extends CloneableEditorProvider {
+ /** Will be called when the document is about to be closed by user */
+ public boolean canClose();
+}
+----
+
+and (possibly) new factory method (possibly because the original method taking just `CloneableEditorProvider` could be enough)
+
+[source,java,subs="{markup-in-source}"]
+----
+
+EditorCookie EditorFactory.createEditor(CloneableEditorProvider2 p);
+----
+
+that will use the new interface for better implementation of the editor while keeping the same interface for client API.
+
+Another example of this kind of evolution can be observed in a situation when the old provider interface is completely wrong and we want to replace it, or enhance the amount of choices be completely new:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+interface PaintProvider {
+ public void paintImage(Image image);
+}
+/** Based on a ability to paint creates new EditorCookie */
+EditorCookie EditorFactory.createEditor(PaintProvider p);
+----
+
+In spite of that the service provider API has changed completely, the whole change is hidden in the factory that translates the calls between old client API to the new provider interface. Moreover there is no clash in evolution. Providers that really wishes to provide `CloneableEditorProvider` do that by implementing directly that interface, providers that want to handle the `closeDocument` call as well do that by implementing `CloneableEditorProvider2` and those that rely on the complet [...]
+
+
+[[Using_games_to_Improve_API_Design_Skills]]
+== Using games to Improve API Design Skills
+
+Having good API design skills is very important for people who work and create an open source framework like NetBeans. It is indeed fine to read and study some [api-design.html API design guidelines], however there is no better learning approach than practicing the design in a situation simulating the reality. Read the [api-fest.html article about API Fest] to learn about the game called _API Fest_ that the NetBeans core team created and played as part of improving their design skills.
+
+
+[NOTE]
+====
+The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/API_Design[http://wiki.netbeans.org/API_Design], that was last modified by NetBeans user Jtulach on 2012-01-07T22:30:47Z.
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/API_Stability.asciidoc b/netbeans.apache.org/src/content/wiki/API_Stability.asciidoc
new file mode 100644
index 0000000..876f5aa
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/API_Stability.asciidoc
@@ -0,0 +1,141 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+= API Stability
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: NetBeans API Stability
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+[[categories]]
+In order to clearly communicate what stage an link:API_Design.asciidoc[API] is
+in, whether it is still being evolved, whether it is expected to ever be real
+_API_ or whether it is stable and ready to use, let us introduce a system of
+link:API_Stability.asciidoc[stability clasification for APIs]. The aim is to
+give the code authors way how to communicate their intention with particular
+feature and others to find out such information.
+
+
+[[private]]
+== Private
+
+*Private* is a category for features that are accessible but are not intended
+for use outside of their component (module). Such features are subject to
+change with every release and depending on them is risky and should be avoided.
+
+
+[[friend]]
+== Friend
+
+*Friend* link:API_Design.asciidoc[API] is used for features accessible to
+specific components in the system, that help to overcome the lack of a real
+stable link:API_Design.asciidoc[API], but are intended only for use between
+these _friend_ components and nobody else. Often friend components are
+developed by the same group of people. A change to this contract can be done
+every release, but owners of those _friend_ components must be notified in
+advance. No one else should depend on such features - the author of this API
+does not have the intent to create a general purpose API.
+
+
+[[devel]]
+== Devel
+
+*Under development* is a name for a contract that is expected to become a
+stable API, but that has not yet been finished. The current state serves as a
+proof of concept, and others are encourage to try it and comment on a dedicated
+mailing list. Incompatible changes may be done between releases, but should be
+rare, not radical and properly announced on the mailing list.
+
+
+[[stable]]
+== Stable
+
+*Stable* interfaces are those that have received a final state and the
+maintainers are ready to support it forever and never change them incompatibly.
+The "forever" and "never" should not be taken as absolute: It is possible to
+change the contract, but only in major versions and only after a careful
+considerations and in cases where it is imperative that a change be made.
+Stable contracts should *preserve the investments* of those entering into
+them (users of an link:API_Design.asciidoc[API]).
+
+
+[[official]]
+== Official
+
+*Official* are <<Stable,stable>> ones and also packaged into one of NetBeans
+official namespaces: `org.netbeans.api` or `org.netbeans.spi` or `org.openide`.
+By packaging a contract into this package (and making it part of a release) one
+notifies others that the contract is
+link:APIDevelopment.asciidoc#Official_APIs_Restrictions[stable - with all the
+consequence] (except the conditional support for
+link:APIDevelopment.asciidoc#Support_for_Early_Adoption[early adoptions] - such
+modules has code base name that ends with with /0). Also, the impact of
+possible incompatible changes to _official_ API should be minimized by
+providing compatibility bridges and keeping binary compatibility even when
+source one is droped (see the <<Preservation_of_Investments,preservation>>
+section).
+
+
+[[third_party]]
+== Third Party
+
+*Third party* interfaces are provided by other parties that do not follow the
+_NetBeans_ rules and thus are hard to classify. It is prefered not to expose
+such interfaces as part of own contracts, in order to insulate users of
+NetBeans APIs from unexpected changes made in the imported interfaces.
+
+
+[[standard]]
+== Standard
+
+*Standard* is similar to the _third party_ classification. Also provided by
+someone out of _NetBeans_, but by someone expected to evolve the interface in
+compatible way (for example link:http://www.jcp.org[JSRs]). The standard is
+expected to not change frequently.
+
+
+[[deprecated]]
+== Deprecated
+
+*Deprecated*. After a while, nearly every _API_, regardless of what state it
+is, becomes obsoleted. Usually a new, better support for the same task has been
+developed which replaces the old _API_. In such case, mark the old _API_
+`deprecated`. A previously stable _API_ that changed its stability
+to `deprecated` shall be supported for reasonable amount of time (a
+release) to communicate to users that they shall migrate from it to the new
+replacement. After that time the API can be removed from the product, while
+trying to preserve it for old clients by making it available in alternative
+ways (e. g. autoupdate centers).
+
+[NOTE]
+====
+The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.
+
+This page was exported from link:API_Design.asciidoc[http://wiki.netbeans.org/API] Stability , that was last modified by NetBeans user Jtulach on 2012-01-07T22:32:21Z.
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
+
diff --git a/netbeans.apache.org/src/content/wiki/Authenticator.asciidoc b/netbeans.apache.org/src/content/wiki/Authenticator.asciidoc
new file mode 100644
index 0000000..e6f28e8
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/Authenticator.asciidoc
@@ -0,0 +1,121 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+= Authenticator
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: Problems
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+
+link:https://netbeans.apache.org[NetBeans] provide its own
+`java.net.Authenticator` implementation and `java.net.ProxySelector`
+implementation. The behavior of these subsystem has always been tight closely
+to their usage in the IDE. Time has come to make it a bit more flexible and
+allow reuse in other link:https://netbeans.apache.org[NetBeans] Platform based
+applications.
+
+
+== Problems
+
+Here is list of known problems. With preferrable way of fixing them. In case
+there are some doubts about the choosen solution, alternative approaches are
+discussed in following section.
+
+
+== Authenticator ignores username:password@ part of the URL
+
+The current Authenticator implementation ignores any information about the name and password specified as part of the URL.
+
+*Resolution:* use it.
+
+== Git support needs a way to suppress Authenticator
+
+The link:https://netbeans.apache.org[NetBeans] Git support wants to connect to
+a URL without asking user a question about the credentials. If the connection
+fails, the `git` itself wants to handle a fallback query.
+
+*Resolution:* Add a pair of methods into *org.openide.util.NetworkSettings*:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+public static <R> R suppressAuthenticationDialog(Callable<R> blockOfCode) throws Exception;
+public static boolean isAuthenticationDialogSuppressed();
+
+----
+
+The `git` module will enter a _suppressed_ mode first, before dealing with the
+URLs. The `Authenticator` implementation will find out it is in this mode
+(while the _blockOfCode_ is running) and will not show any user visible dialogs
+at all.
+
+NOTE: The cooperation between `NetworkSettings` and
+link:https://netbeans.apache.org[NetBeans] `Authenticator` is proprietary. If a
+system is using other `Authenticator` implementation, it must call
+`_isAuthenticationDialogSuppressed()_`.
+
+
+[[Dynamic_credentials]]
+=== Dynamic credentials
+
+Most of the proxy and network credentials are currently read from a default link:https://netbeans.apache.org[NetBeans] storage. This may not be ideal for other Platform aplications storing the settings in a different way or computing them dynamically.
+
+*Resolution*: Abstract the way following values are obtained:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+protected abstract String getProxyUserName(URI u);
+protected abstract char[] getProxyPassword(URI u);
+protected abstract String getProxyHost(URI u);
+protected abstract String getProxyPort(URI u);
+// possibly:
+protected abstract boolean isProxyAuthentication(URI u);
+
+----
+
+let other application to register other than default implementation which can read the values from whatever source it wants.
+
+
+[[Open_Questions]]
+== Open Questions
+
+Eclipse is solving similar problem. Anyone knows how that is handled? org.eclipse.jgit is not reusing it directly (has no dependency), but somehow the system works together and we should understand how.
+
+The link:https://bits.netbeans.org/dev/javadoc/org-netbeans-libs-git/index.html?overview-summary.html[git client library] is link:https://netbeans.apache.org[NetBeans] independent and can be shared in other products. Should it use _suppressAuthenticationDialog_ by itself or should each caller wrap their calls into _suppressAuthenticationDialog_ *Callable*?
+
+NetBeans uses link:http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-keyring/org/netbeans/api/keyring/Keyring.html[Keyring API] for secure storage for user's passwords. _Keyring_ uses native support in given platform. Consider using _Keyring_ in SPI for dynamic network credentials.
+
+
+[NOTE]
+====
+The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/Authenticator[http://wiki.netbeans.org/Authenticator] , that was last modified by NetBeans user Jglick on 2011-09-20T13:23:07Z.
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/BackwardCompatibilityPatches.asciidoc b/netbeans.apache.org/src/content/wiki/BackwardCompatibilityPatches.asciidoc
new file mode 100644
index 0000000..815c8e2
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/BackwardCompatibilityPatches.asciidoc
@@ -0,0 +1,292 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+
+= Backwards compatibility support
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: Backwards compatibility support
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+NetBeans contains deprecated obsolete code, which is typically left in place
+for several releases. In addition to add polution to the API, it also increases
+the number of dependencies to both ancient modules and Java platform. The
+deprecated code is a dead weight in the released NB product, as the shipped
+modules are (or should be) upgraded to work with API modules in their current
+versions, not using deprecated APIs.
+
+The purpose of this backward compatible support is to preserve binary
+compatibility for unmaintained modules, or 3rd party modules with a different
+release cycle while allowing to remove obsolete code from the public APIs.
+
+The following techniques can be used for backward compatibility:
+
+
+[[Accessor_method]]
+== Accessor method
+
+A compatible implementation may need to access the internals possibly from a
+different module (classloader).
+link:http://bits.netbeans.org/dev/javadoc/org-openide-modules/org/openide/modules/PatchedPublic.html[@PatchedPublic]
+annotation currently serves this purpose.
+
+The annotated method is *patched* to be public at runtime, while the class is
+being loaded. The calling code is typically resides in the same package,
+although a different module with an implementation dependency. Using
+_@PatchedPublic_ it can access the method even at runtime, although from a
+different classloader.
+
+Note that this approach _still_ requires that method signature dependencies
+affect the API module dependency closure. All types referenced from the
+signature must be present for the compilation and execution of the API module.
+If the referenced type contains an illegal platform or library dependency in
+its API/impl, then the illegal component infects even the API module.
+
+
+[[Automatic_module_dependencies]]
+== Automatic module dependencies
+
+If some classes are *split* from module "A" into a different module (say B),
+source and binary compatibility can be retained if the module "A" declares "B"
+as an additional implied dependency for clients who depend on an older version
+of the module. Clients compiled against older version will receive the
+additional dependency at both run-time and compile-time.
+
+During compilation, a special file in _config_ area will be generated. The
+generated file will be recognized when dependent module load, and their
+dependencies will be transformed according to the description.
+
+The automatic dependencies must be stored in the file
+`module-automatic-deps.xml` in the module project's root folder. A typical
+example of dependencies implied when a module is split to several ones is shown
+below:
+
+[source,xml,subs="{markup-in-source}"]
+----
+
+ <!DOCTYPE transformations PUBLIC "-//NetBeans//DTD Module Automatic Dependencies 1.0//EN" "link:http://www.netbeans.org/dtds/module-auto-deps-1_0.dtd[http://www.netbeans.org/dtds/module-auto-deps-1_0.dtd]">
+
+ <transformations version="1.0">
+ <!-- unimportant content -->
+ <transformationgroup>
+ <description>Separation of desktop and cleanup</description>
+ <transformation>
+ <trigger-dependency type="older">
+ *<module-dependency codenamebase="org.openide.filesystems" spec="9.0"/>*
+ </trigger-dependency>
+ <implies>
+ <result>
+ *<module-dependency codenamebase="org.openide.filesystems.nb"/>*
+ *<module-dependency codenamebase="org.openide.filesystems.compat8"/>*
+ </result>
+ </implies>
+ </transformation>
+ </transformationgroup>
+
+ </transformations>
+----
+
+
+[[Module_Fragment]]
+== Module Fragment
+
+If a class in a module A patches a class in module B, the system must esnure proper visibility between A and B classloaders. With the Compatible Superclass approach, the compatibility class in A typically uses types defined by B, but B must see A's contents at run-time as B class will be made to extend A type (see below). The simplest way is to join contents of A and B in the same classloader.
+
+If a module's MANIFEST.MF defines OpenIDE-Module-Fragment-Host: header, the module becomes a Module Fragment and its contents is included into the fragment host's module
+classloader.
+
+
+[[Example]]
+=== Example
+
+This is an example MANIFEST.MF of openide.filesystems module:
+
+[source]
+----
+ Manifest-Version: 1.0
+ OpenIDE-Module: *org.openide.filesystems*
+ OpenIDE-Module-Localizing-Bundle: org/openide/filesystems/Bundle.properties
+ OpenIDE-Module-Layer: org/openide/filesystems/resources/layer.xml
+ OpenIDE-Module-Specification-Version: 9.0
+----
+
+A compatibility support module, which needs to merge with filesystems API at runtime uses the following MANIFEST:
+
+[source]
+----
+
+ Manifest-Version: 1.0
+ OpenIDE-Module: org.openide.filesystems.compat8
+ OpenIDE-Module-Localizing-Bundle: org/openide/filesystems/compat8/Bundle.properties
+ OpenIDE-Module-Specification-Version: 9.0
+ *OpenIDE-Module-Fragment-Host: _org.openide.filesystems_ *
+----
+
+There's no dependency from the *real API module* to the patch; the patch
+depends on the API module. The patch module may be eventually not present at
+all, if compatibility is not needed.
+
+
+[[Compatible_superclass]]
+== Compatible superclass
+
+Because of JVM definition of method resolution, JVM looks not only in the class hosting the target method and specified as part of the Method Reference, but also in _superclasses_ of that class. It's therefore binary-compatible to *move the methods to some superclass*.
+
+We must still prevent the superclass from appearing in the `extends` clause of the source, in order not to retain the dependencies from the superclass' dependency closure (the requirement was to avoid them). At run-time, the API class A which was compiled as extending superclass S, will be patched to extend another superclass, C. Provided that C extends S, type checks in the
+running JVM should not be affected. The superclass C can then add methods with illegal dependencies in their transitive dependency closure.
+
+The class which delivers the binary-compatible implementation must be annotated using *@PatchFor* annotation, which also identifies the
+target class which should be modified at run-time. To preserve inheritance hierarchy properties, there are some rules to be followed.
+Given API class "A" which extends "X", and binary-compatible implementation class "A"
+
+* I must also extend X
+* I must define the constructors with the same signature as X
+* A must contain a default constructor, implicit or explicit
+
+In addition, A and I must be loaded by the same classloader. To instruct NetBeans module system to do so, the module that contain I must
+list the following Manifest entry:
+
+[source]
+----
+OpenIDE-Module-Fragment-Host: codename
+----
+
+where the `codename` identifies the original module which contains API class A.
+
+
+[[Example_2]]
+=== Example
+
+The AbstractFileSystem, in version 8.0 and earlier contains a number of @deprecated or obsolete methods:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+ public abstract class *FileSystem* {
+ public abstract SystemAction[] getActions();
+ @Deprecated
+ public void prepareEnvironment(*FileSystem.Environment* env) throws EnvironmentNotSupportedException {
+ ...
+ }
+ ...
+ }
+----
+
+The methods are now moved to a class *FileSystemCompat*, which resides in a different module - _openide.filesystems.compat8_:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+ *@PatchFor(_FileSystem.class_)*
+ public abstract class FileSystemCompat {
+ public abstract SystemAction[] getActions();
+ @deprecated
+ public void prepareEnvironment(*FileSystem$Environment* env) throws EnvironmentNotSupportedException {
+ ...
+ }
+ ...
+ }
+----
+
+The example also shows, how a _static member type_ may be moved to a deprecated module; JVM signature does not contain information that _FileSystem.Environment_ is a member type. *FileSystem$Environment* has the same signature.
+
+
+[[Constructor_delegate]]
+== Constructor delegate
+
+API class A may have a constructor, which is no longer acceptable, because of
+its signature dependencies. If the constructor was just implemented in an
+'unlucky' way, the implementation could be lobotomized, but if the
+constructor's signature contain an unwanted dependency, it should be rather
+removed at all from the class.
+
+To preserve backward compatibility, the constructor has to be added back at
+run-time. Although JVM linking algorithm would eventually find _<init>()V_
+method to call after new, the constructor "inherited" from the superclass would
+not be able to initialize the API class fields.
+
+The initialization of the original API class is implemented by its default
+constructor - this means the API class *must have default constructor*, even
+though it is private. _Delegation to other A constructors is not implemented
+yet, but is feasible._
+
+Initialization of the superclass, or possibly setup of API (A) fields are
+delegated to a _static "factory" method_ in the `@PatchFor` superclass. The
+initialization method must be annotated with *@ConstructorDelegate*. It's first
+parameter must be of type of the compatible superclass itself and the rest of
+parameters must be the same as the to-be-generated constructor in the API
+class. Modifiers and declared exceptions are copied to the generated
+constructor.
+
+
+[[Example_3]]
+=== Example
+
+`JarFileSystem` has a constructor which takes *FileSystemCapability*. Since the
+type is long deprecated and we want to remove it, the relevant implementation
+moves off to the patch superclass:
+
+[source,java,subs="verbatim,quotes"]
+----
+
+ *@PatchFor(JarFileSystem.class)*
+ public abstract class JarFileSystemCompat extends AbstractFileSystem {
+ public JarFileSystemCompat() {
+ super();
+ }
+
+ *@ConstructorDelegate*
+ public static void createJarFileSystemCompat(_JarFileSystemCompat jfs_, *FileSystemCapability cap*) *throws IOException* {
+ FileSystemCompat.compat(jfs).setCapability(cap);
+ }
+ ...
+ }
+----
+
+The *1st* argument of the `@ConstructorDelegate` method receives the newly
+created instance to be initialized. Since `AbstractFileSystem` does not (in
+sources) derive from FileSystemCompat, some runtime-typing magic must be done.
+
+In effect, the bytecode generator creates a constructor in `JarFileSystem`:
+
+[source,java,subs="verbatim,quotes"]
+----
+
+ public JarFileSystem(*_FileSystemCapability cap_*) *_throws IOException_* {
+ this();
+ setCapability(cap);
+ }
+----
+
+
+[NOTE]
+====
+The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/BackwardCompatibilityPatches[http://wiki.netbeans.org/BackwardCompatibilityPatches] , that was last modified by NetBeans user Sdedic on 2014-05-07T12:45:06Z.
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/BackwardCompatibilityTesting.asciidoc b/netbeans.apache.org/src/content/wiki/BackwardCompatibilityTesting.asciidoc
new file mode 100644
index 0000000..2512067
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/BackwardCompatibilityTesting.asciidoc
@@ -0,0 +1,116 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+
+= Backward Compatibility Testing of NetBeans Platform
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:jbake-status: published
+:syntax: true
+:description: Backward Compatibility Testing of NetBeans Platform
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+We want to assure the backward compatibility of NetBeans Platform/IDE.
+
+
+[[What_is_backward_compatibility]]
+== What is backward compatibility
+
+The goal when producing new version of NetBeans Platform is to be backward compatible, unless otherwise stated. This means that if you developed a module/plugin for version A of the platform then it should work even in platform version B that was developed a few years later. If there is a module for which the previous statement is not true, then the
+compatibility is compromised. Discovering such modules is generally bad sign. It can either mean that there is an unwanted incompatible change, and in such case we shall fix it prior to release, or this change is desirable and highly justified, and in such case it should be properly documented. In either case, backward compatibility is the strongest commitment of the NetBeans platform. Undesired incompatible changes have to be eliminated.
+
+
+[[How_can_you_help]]
+== How can you help
+
+If you develop a module for NB IDE or an application based on NB Platform then it is in your own interest to know if your module works with the newer version of IDE/Platform. You can link:BackwardCompatibilityTesting#Howtotestit.html[test the backward compatibility] by yourself and let us know the result of your testing. We will evaluate your results and report bugs to the developers. Or you can report the bugs by yourself.
+
+There are multiple levels of compatibility. Ability to compile old code against new version. Ability to link old binaries with new version and last, but definitely not least, ability to guarantee that behavior of NetBeans libraries remains unchanged. That is the highest level of compatibility.
+
+
+[[How_to_test]]
+== How to test
+
+
+[[Modules_for_NetBeans_IDE]]
+=== Modules for NetBeans IDE
+
+
+
+1. install the module to newer version of IDE. E.g. module was developed for NB 6.0 (previous version). Install it to NB 6.1 (next version).
+* module have to install correctly -> no exceptions/no warning/no missing dependencies etc.
+. test module functionality
+* it should work without any unexpected exceptions
+
+[[Application_based_on_NB_RCP]]
+=== Application based on NB RCP
+
+
+
+1. install the application
+. replace the RCP with newer (next) version -> replace platformX directory in the platformX+1 from the latest version of IDE
+. start your application
+* the application works correctly
+* your tests pass
+* If not sent us the results of your test or write down what was wrong
+
+
+[[How_to_join]]
+== How to join
+
+* Wait for a message "Backward Compatibility Testing Call for NB VERSION" on nbdev@netbeans.org
+* Test your module/application with NB VERSION of NetBeans
+
+* test the functionality with automated tests or manually
+* Let us know the results at compatibility@platform.netbeans.org
+
+* the e-mail *must* contain:
+
+
+1. brief module/application description - we don't want to test the module/app by ourself however we would like to know what it is doing
+. platform/IDE version that the application/module was created on/for
+. test results - summary of passed/failed tests is enough
+. bug numbers (if you filled any)
+* we will contact you back if we will need a more informations
+
+
+[[For_late_comer_or_people_that_have_problem_with_deadlines]]
+== For late comer or people that have problem with deadlines
+
+* Fell free to mail us results of your backward compatibility testing anytime
+* Fill bugs about your problems
+
+
+
+[NOTE]
+====
+
+The content in this page was kindly donated by Oracle Corp. to the
+Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/BackwardCompatibilityTesting[http://wiki.netbeans.org/BackwardCompatibilityTesting] ,
+that was last modified by NetBeans user Admin
+on 2009-11-04T20:54:25Z.
+
+This document was automatically converted to the AsciiDoc format on 2020-03-15, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/BugtrackingAPISPIUseCases.asciidoc b/netbeans.apache.org/src/content/wiki/BugtrackingAPISPIUseCases.asciidoc
new file mode 100644
index 0000000..ee4bbb8
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/BugtrackingAPISPIUseCases.asciidoc
@@ -0,0 +1,251 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+= SPI - Service Provider Interface
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: SPI
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+This document describes the basic SPI/API requirements requested by the needs
+of the bugtracking infrastructure and other dependent subsystems of the IDE.
+
+For a Bugtracking plugin implementation it is essential to support the
+following functionality:
+
+== SPI: Service Provider Interface
+
+
+[[Connector]]
+=== Connector
+
+
+[[Registration]]
+==== Registration
+
+register a Butracking plugin
+
+
+[[Connector_Information]]
+==== Connector Information
+
+provide basic information about a Bugtracking plugin - name, tooltip, icon, ...
+
+
+[[Repository]]
+=== Repository
+
+provide functionality to manage Repository lifecycle
+
+
+[[Create_a_Repository]]
+==== Create a Repository
+
+create and validate a Bugtracking repository
+
+
+[[Edit_Repository_Settings]]
+==== Edit Repository Settings
+
+edit and validate repository settings
+
+
+[[Remove_a_Repository]]
+==== Remove a Repository
+
+remove a Bugtracking repository
+
+
+[[Accessing_Issues]]
+=== Accessing Issues
+
+Provide Issues from a Repository by:
+
+
+[[Quick_Text_Search]]
+==== Quick Text Search
+
+provide Issues from a Repository based on a simple text criteria - match text with id or summary
+
+
+[[By_Issue_ID]]
+==== By Issue ID
+
+provide Issues from a Repository given by their id
+
+
+[[Access_Issues_via_Queries]]
+==== Access Issues via Queries
+
+provide Issues from a Repository given by a parametrised Queries
+
+
+[[Query_Management]]
+=== Query Management
+
+provide functionality to manage Query lifecycle:
+
+
+[[Create_and_Edit_Queries]]
+==== Create and Edit Queries
+
+provide a Query editor component capable to to create, edit and rename Queries and to notify the IDE about the state of changes in the editor
+
+
+[[Remove_a_Query]]
+==== Remove a Query
+
+remove a Query associated with a Repository
+
+
+[[List_Queries]]
+==== List Queries
+
+provide list of saved Queries associated with a Repository and notify about eventual changes in the saved queries list
+
+
+[[Refresh_a_Query]]
+==== Refresh a Query
+
+execute the Query against the remote server and retrieve Issues matching the query criteria
+
+
+[[List_Issues]]
+==== List Issues
+
+provide list of Issues returned by the last Query refresh
+
+
+[[Issue_Management]]
+=== Issue Management
+
+provide functionality to access and manipulate Issues:
+
+
+[[Create_and_Edit_Queries_2]]
+==== Create and Edit Queries
+
+provide an Issue Editor component capable to create and edit Issues and to notify about the state of changes in the editor
+
+
+[[Basic_Issue_Information]]
+==== Basic Issue Information
+
+provide basic issue information - id, summary, priority, finished state, relationship to other issues (parent/child), etc ...
+
+
+[[Incoming_Changes]]
+==== Incoming Changes
+
+*(Not mandatory)*
+provide status information about incoming issue changes
+
+
+[[Refresh_Issue]]
+==== Refresh Issue
+
+refresh the current Issue state from the remote server
+
+
+[[Issue_Scheduling]]
+==== Issue Scheduling
+
+set and provide information about locally private and/or remote Issue scheduling. *(Not mandatory.)*
+
+
+[[Offline_Work]]
+=== Offline Work
+
+Persist Issue and Query state between IDE sessions. Notify and provide information about an Issues current local state. *(Not mandatory.)*
+
+
+[[Outgoing_Changes]]
+==== Outgoing Changes
+
+provide status information about outgoing (local) issue changes
+
+
+[[List_local_changes]]
+==== List local changes
+
+provide list of locally changed issues
+
+
+[[Submit]]
+==== Submit
+
+submit locally changed issues
+
+
+[[API]]
+== API: Application Provider Interface
+
+the bugtracking infrastructure will provide the following functionality for other subsystems to support:
+
+
+[[List_Repositories]]
+=== List Repositories
+
+provide a list of all existing repositories
+
+
+[[Access_Issues_by_Queries]]
+=== Access Issues by Queries
+
+provide a list of existing Queries for each Repository and a list of Issues for each Query (e.g for the needs of Team Support)
+
+
+[[Quick_Text_Search_2]]
+=== Quick Text Search
+
+provide "quick" Issue search by a simple text criteria - (e.g for the needs of VCS Commit hooks, and patch integration)
+
+
+[[Issue_Operations]]
+=== Issue Operations
+
+provide Issue operations:
+
+* add comment, close and submit an issue (VCS Commit hooks)
+* create a new issue preset with summary and description (create Issue from Action Items or Hudson)
+* attach files to an Issue (export and attach patch to an issue from VCS)
+
+
+[[Hyperlink_Issue_References]]
+=== Hyperlink Issue References
+
+* parse text for issue references in the IDE (comments in source code editors, or in commit messages in VCS or in code comments)
+* open Issues by ID
+
+
+[NOTE]
+====
+The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/BugtrackingAPISPIUseCases[http://wiki.netbeans.org/BugtrackingAPISPIUseCases] , that was last modified by NetBeans user Tstupka on 2013-11-12T14:11:14Z.
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/BugtrackingCookbook.asciidoc b/netbeans.apache.org/src/content/wiki/BugtrackingCookbook.asciidoc
new file mode 100644
index 0000000..ddc2646
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/BugtrackingCookbook.asciidoc
@@ -0,0 +1,260 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+
+= Bugtracking Plugin Cookbook
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: Bugtracking Plugin Cookbook
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+
+This is a quick how-to for creating a plug-in module for a bugtracking system.
+
+IDE supports several bugtracking systems out-of-the-box but there are numerous
+other systems still not directly supported in the IDE. We want to encourage
+community members and especially creators of these bugtracking systems to come
+and create the support for NetBeans. This how-to tries to make this process as
+easy as possible and puts you right into the process of coding the plugin
+itself without first messing with the Bugracking SPI and NetBeans API
+specifics.
+
+
+[[Setup]]
+== Setup
+
+
+[[Working_Environment]]
+=== Working Environment
+
+* Clone and build the main NetBeans repository at link:http://github.com/apache/netbeans[]
+
+*Download the Bugtracking skeleton/demo Module*
+
+* Download the project skeleton - link:http://wiki.netbeans.org/wiki/images/5/5f/XXXBugtracking.zip[]
+* Unzip the skeleton code to a directory where you will develop the module
+
+*Build and test the demo Module*
+
+* Start NetBeans and open the demo project
+* Build and Run the project to check that all is set up
+* Scan TODOs in the code for primary interest points
+
+
+[[How_To]]
+== How To
+
+Please note that until not mentioned otherwise, all classes are from the
+link:http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/package-summary.html[org.netbeans.modules.bugtracking.spi]
+package.
+
+
+[[Register_a_Connector]]
+=== Register a Connector
+
+* Create an implementation of `BugtrackingConnector` and register it via the `BugtrackingConnector.Registration` annotation.
+
+* see also `org.yourorghere.xxx.XXXConnector` in the attached project sample project
+[source,java,subs="{markup-in-source}"]
+----
+@BugtrackingConnector.Registration (
+ id=XXXConnector.ID,
+ displayName=XXXConnector.NAME,
+ tooltip=XXXConnector.NAME
+)
+public class XXXConnector implements BugtrackingConnector {
+ public static final String NAME = "XXX Bugracking";
+ public static final String ID = "org.yourorghere.xxx.xxxconnector";
+...
+}
+----
+
+
+[[Handle_Repositories]]
+=== Handle Repositories
+
+
+[[Create]]
+==== Create
+
+Invoked by user action from the Tasks Dashboard.
+
+* the method `BugtrackingConnector|createRepository()` will be invoked when a new repository is supposed to be created. The infrastructure opens then a repository editor dialog and takes care for storing the confirmed repository data.
+* see the javadoc on `RepositoryController` to find out how the repository editor UI is handled.
+* those repository data are used the next time when that repository is needed and no object is created yet (e.g. in a new IDE session). This will be done via `link:http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/BugtrackingConnector.html#createRepository(org.netbeans.modules.bugtracking.spi.RepositoryInfo)[BugtrackingConnector.createRepository(RepositoryInfo)]`
+
+
+[[Setup_2]]
+==== Setup
+
+use the link:http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/BugtrackingSupport.html#createRepository(R,%20org.netbeans.modules.bugtracking.spi.IssueStatusProvider,%20org.netbeans.modules.bugtracking.spi.IssueScheduleProvider,%20org.netbeans.modules.bugtracking.spi.IssuePriorityProvider,%20org.netbeans.modules.bugtracking.spi.IssueFinder)[BugtrackingSupport.createRepository(R, ...)]
+ method when creating a Repository instance, so that the the infrastructure
+can setup your repo instance with additional feature providers.
+
+* for more information see the javadoc in:
+** `RepositoryProvider` (mandatory)
+** `QueryProvider` (mandatory)
+** `IssueProvider` (mandatory)
+** `IssueStatusProvider` (optional)
+** `IssuePriorityProvider` (optional)
+** `IssueScheduleProvider` (optional)
+** `IssueFinder` (optional)
+
+* see also `org.yourorghere.xxx.XXXConnector` in the attached sample
+
+
+[[Handle_Queries]]
+=== Handle Queries
+
+
+[[Creating]]
+==== Creating
+
+Invoked by user action from the Tasks Dashboard.
+
+* the method `RepositoryProvider|createQuery®` is invoked when a new Query
+is supposed to be created. Create and return an object representing your
+Query at that place.
+* to find out how the lifecycle of queries is handled, see the javadoc of:
+** `QueryController`
+** `QueryProvider`
+* once a Query is saved/persisted, it is expected to be returned by `RepositoryProvider|getQueries®`.
+
+
+[[Executing]]
+==== Executing
+
+Invoked by user action from the Tasks Dashboard or in automatically by a customisable time interval.
+
+* see the javadoc on:
+** link:http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/QueryProvider.html#setIssueContainer(Q,%20org.netbeans.modules.bugtracking.spi.QueryProvider.IssueContainer)[`QueryProvider.setIssueContainer(Q, IssueContainer)`]
+** `QueryProvider|refresh(Q)`
+** `IssueContainer`
+
+* see also how Queries are handled in the attached sample - `org.yourorghere.xxx.XXXRepositoryProvider.createQuery()`.
+
+
+[[Handle_Issues]]
+=== Handle Issues
+
+
+[[Creating_2]]
+==== Creating
+
+Invoked by user action from the Tasks Dashboard.
+
+* when a new Issue is supposed to be created the method `RepositoryProvider|createIssue®` will be invoked. Create and return an object representing your Issue.
+* to find out how the lifecycle of particular issues is handled, see the javadoc of:
+** `IssueController`
+** `IssueProvider`
+
+
+[[Retrieving_from_a_remote_repository]]
+==== Retrieving from a remote repository
+
+* by Query - see the javadoc on:
+** `QueryProvider|refresh(Q)`
+** `IssueContainer`
+* by Issue ID or text criteria - see the javadoc on:
+** link:http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/RepositoryProvider.html#getIssues(R,%20java.lang.String...)[`RepositoryProvider.getIssues(R, String)`]
+** link:http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/RepositoryProvider.html#simpleSearch(R,%20java.lang.String)[`RepositoryProvider.simpleSearch(R, String)`]
+
+
+[[Status_-_local_and_remote_changes]]
+==== Status - local and remote changes
+
+Outgoing and incoming Issue changes are annotated (via coloring) in Query result lists in the Tasks Dashboard.
+
+In case you want to provide status values for changes in your Issues then you have to implement the `IssueStatusProvider` interface and provide it via the `link:http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/BugtrackingSupport.html#createRepository(R,%20org.netbeans.modules.bugtracking.spi.IssueStatusProvider,%20org.netbeans.modules.bugtracking.spi.IssueScheduleProvider,%20org.netbeans.modules.bugtracking.spi.IssuePriorityProvid [...]
+
+* for more info see:
+** javadoc on `IssueStatusProvider`
+** and `org.yourorghere.xxx.XXXIssueStatusProvider`
+* link:http://wiki.netbeans.org/TaskDashboardDesignSpec[The Tasks Dashboard UI spec]
+* note that this feature is not mandatory
+
+
+[[Scheduling]]
+==== Scheduling
+
+In the Tasks Dashboard it is possible to set user local scheduling information (e.g. what date the user plans to start working on the issue) and accordingly to categorise Issues given by that scheduling data (e.g list Issues scheduled for Today, This Week, etc.).
+
+In case you want to provide local scheduling information for your Issues then you have to implement the `IssueScheduleProvider` interface and provide it via the `link:http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/BugtrackingSupport.html#createRepository(R,%20org.netbeans.modules.bugtracking.spi.IssueStatusProvider,%20org.netbeans.modules.bugtracking.spi.IssueScheduleProvider,%20org.netbeans.modules.bugtracking.spi.IssuePriority [...]
+
+* for more info see:
+** javadoc on `IssueScheduleProvider`
+** and `org.yourorghere.xxx.XXXIssueScheduleProvider`
+* note that this feature is not mandatory
+
+
+[[Priority]]
+==== Priority
+
+In case you want the Tasks Dashboard to show an priority icon next to an Issue in a Query result list then you have to implement the `IssuePriorityProvider` interface and provide it via the `link:http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/BugtrackingSupport.html#createRepository(R,%20org.netbeans.modules.bugtracking.spi.IssueStatusProvider,%20org.netbeans.modules.bugtracking.spi.IssueScheduleProvider,%20org.netbeans.modules. [...]
+
+* for more info see:
+** javadoc on `IssuePriorityProvider`
+** and `org.yourorghere.xxx.XXXIssuePriorityProvider`
+* note that this feature is not mandatory
+
+
+[[IDE_integration]]
+=== IDE integration
+
+
+[[Issue_references_in_text]]
+==== Issue references in text
+
+Issue references can be hyperlinked in various places in the IDE - e.g. in source code comments or versioning commit messages.
+
+The infrastructure parses for some default patters (e.g. Issue #12345), but in
+case your remote repository comes with and untypical issue format, like for
+example in case of JIRA, where the issue key is more complex ("Issue
+#JIRAPOJECT-12345") you can provide your own `IssueFinder` implementation via
+link:http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/BugtrackingSupport.html#createRepository(R,%20org.netbeans.modules.bugtracking.spi.IssueStatusProvider,%20org.netbeans.modules.bugtracking.spi.IssueScheduleProvider,%20org.netbeans.modules.bugtracking.spi.IssuePriorityProvider,%20org.netbeans.modules.bugtracking.spi.IssueFinder)[`BugtrackingSupport.html.createRepository(R, ...)`].
+* for more info see javadoc on `IssueFinder`
+
+
+[[Versioning_Commits]]
+==== Versioning Commits
+
+On a versioning commit it is possible to select an issue and to add commit info and to close it eventually. All that has to be done to support this case is to implement `link:http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/IssueProvider.html#addComment(I,%20java.lang.String,%20boolean)[IssueProvider.addComment(I, String, boolean)]`.
+
+
+[[Attaching_Patches]]
+==== Attaching Patches
+
+When creating an patch via Versioning, it is possible to select an issue and to attach that patch to the issue. All that has to be done to support this case is to implement `link:http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-bugtracking/org/netbeans/modules/bugtracking/spi/IssueProvider.html#attachFile(I,%20java.io.File,%20java.lang.String,%20boolean)[IssueProvider.attachFile(I, File, String, boolean)]`.
+
+
+[NOTE]
+====
+The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/BugtrackingCookbook[http://wiki.netbeans.org/BugtrackingCookbook] , that was last modified by NetBeans user Tstupka on 2014-01-07T13:43:11Z.
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/BuildSystemHowTo.asciidoc b/netbeans.apache.org/src/content/wiki/BuildSystemHowTo.asciidoc
new file mode 100644
index 0000000..8270a19
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/BuildSystemHowTo.asciidoc
@@ -0,0 +1,523 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+
+= NetBeans 4.x Project & Build System How-To
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: NetBeans 4.x Project & Build System How-To
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+:date: June 21, 2006
+:author: Jesse Glick
+
+
+[[Overview]]
+== Overview
+
+This guide should give developers of NetBeans modules (extensions) a basic idea
+of how to write new project types for NetBeans 4.x, as well as use certain
+importants parts of the project and build system functionality from other kinds
+of modules.
+
+The reader is assumed to be familiar with the basics of developing NetBeans
+modules: how to compile Java sources against API-providing modules, make the
+JAR, write the manifest and XML layer, register services in global lookup, etc.
+
+For background, the reader is encouraged to first look at the [design.html
+general design document] which explains how the different pieces of the
+architecture work together to provide the user functionality.
+
+Quick architectural summary:
+
+1. The NetBeans IDE (starting with version 4.0) organizes user work into projects. Each project corresponds to exactly one project folder on disk. (A given disk folder may be a project folder or not; you cannot have two projects in one folder.)
+. A project owns all files inside its project folder or subfolders (except when a subfolder is itself another project folder, which is allowed); it might also own files located elsewhere on disk, to permit a user to keep IDE-specific configuration separate from existing “pristine” sources.
+. There are different types of projects available, according to what modules you have installed. Different project types may behave very differently, or look almost alike, depending on their intent.
+. A project defines what appears beneath its node in the *Projects* tab—sometimes called its logical view. It can also define a customizer action, usually opening a properties dialog.
+. A project can be opened or closed via the GUI. It can also be loaded though not open; an open project is however always loaded. A project can be garbage collected if it is closed; attempting to refer to it again (via its project directory) will automatically load it again.
+. A project may list subprojects, other projects it somehow depends on. This is used mainly when opening a project using the *Open Project* action.
+. The IDE defines certain generic actions such as *Build* which can be invoked on a project, which have corresponding commands, simple strings like `build`. Some actions can be sensitive to the selected file. Often Apache Ant is used as a build tool to produce a final program or other delierable from sources, but this is not required.
+. Interaction between project implementations and other functionality in the IDE is normally done using queries, a pattern whereby a client can ask a concrete question (e.g. ClassPath.getClassPath(someJavaFile, ClassPath.COMPILE)) and possibly receive an answer; query implementations are registered (using `Lookup.default`) by any modules, and asked in turn. For queries mentioned here, usually the query implementation may be registered in the project (using `Project.lookup`) rather than g [...]
+. Though project type providers are allowed a great deal of leeway in how they implement the project SPIs, there is a fairly extensive SPI support suite which assumes that the project uses Ant as a build tool, and defines a number of convenience implementations optimized towards this system.
+
+NOTE: all API classes and interfaces are referred to by simple name. You can look up the Javadoc for any of these classes quickly using the link:https://bits.netbeans.org/dev/javadocallclasses.html[master class index] for the NetBeans APIs.
+
+
+[[How_to_Write_a_Project_Type_.28Generally.29]]
+== How to Write a Project Type (Generally)
+
+This section discusses general things you need to do in order to write a new project type. Later on we will discuss more concrete suggestions for Ant-based projects using the standard infrastructure.
+
+Generally a project type should be contained in a module dedicated to implementing that project type. _Do not expose any APIs from this module._ If other modules need special information about your project’s structure not available through the existing APIs, you can define new APIs _in separate API modules_ that both the clients and your project type depend on. This rule helps enforce a clean architecture on the system and ensures that other project types could mimic some of the behavior [...]
+
+An interesting tutorial on writing a (non-Ant-based) project type from scratch is available: link:http://openide.netbeans.org/povraytutorial/[Tim Boudreau’s POV-Ray tutorial]
+
+
+[[Decide_on_a_Project_Layout]]
+=== Decide on a Project Layout
+
+The first step for any kind of project type is to decide what the project will look like! You should have a clear idea of what files will reside in the project directory (or perhaps externally), using what file names, what the contents should be, what files will be updated by the IDE’s GUI, what by text editing, how future updates will affect file formats, etc.
+
+If you use the standard Ant-based infrastructure (below), some of these decisions are made for you.
+
+Most project types will define an `AntBasedProjectType` and keep basic project metadata in `''$projdir''/nbproject/project.xml` (below). If you do not do this, e.g. if you need to support a third-party project layout (such as Apache Maven uses), then you will need to implement `ProjectFactory` yourself to recognize and load projects using your format. A project factory should be designed to be able to quickly reject candidate directories which are _not_ in your layout. (Positive identifi [...]
+
+
+[[Write_the_Project_Object]]
+=== Write the Project Object
+
+Every project is represented by a `Project` object, which is created by your factory. Its only mandatory behavior is to be able to report the project directory it is associated with. Other than that, all of its behavior is controlled by its `Lookup`, basically a bag of optional capabilities. Usually `org.openide.util.lookup.Lookups` can be used to make a `Lookup` with a fixed list of entries.
+
+_All outside code_ should interact with your project via interfaces found in its lookup. Outside code can check to see if a given project has a capability, and if so, use it. _Never make your `Project` implementation class publicly accessible._ Whatever capabilities you wish to expose, do so from the lookup—you can define additional interfaces to expose to clients (public or semi-public, in API-exposing modules) and add implementations to your lookup (in non-public classes in your projec [...]
+
+
+[[What_to_Put_in_Lookup]]
+=== What to Put in Lookup
+
+Since all the project’s behavior is controlled by its lookup, the question becomes: what interfaces should I implement? There is a suggested list in the Javadoc for `Project.getLookup()`. Here is an overview of major kinds of interfaces and why you might need them.
+
+
+[[General_Appearance]]
+=== General Appearance
+
+Almost all project types will want to define their general appearance and behavior in the IDE’s GUI.
+
+`ProjectInformation`:: Lets you control the display name and icon of the project. Typically all projects of a given type will share an icon, but there may be badging etc. applied as well, and it is possible to have basically different icons depending on project metadata.
+`LogicalViewProvider`:: Controls the display in the *Projects* tab. You can show whatever subnodes you like, according to the project’s semantics. Typically you will show important source roots (try `PackageView` in the case of Java package roots), or important files. You can also show nodes which do not directly correspond to individual files—e.g. an EJB project shows EJB and web services nodes which are derived from combinations of source files and deployment descriptor information.The [...]
+`CustomizerProvider`:: Implements the *Project Properties* action in the *File* menu (also `CommonProjectAction.customizeProjectAction`). Usually this action should open a dialog containing general GUI configuration for the project, according to its needs. Of course the project may expose additional UI for customization, if appropriate, using context menu items on the project node, subnodes in the logical view, etc.
+
+
+[[File_Structure_and_Templates]]
+=== File Structure and Templates
+
+Most project types will wish to define some aspects of how their source directories are laid out, what they contain, and what may be added to them.
+
+`Sources`:: Basic information about what directories are contained in the project. Technically optional—the default assumption is that the project contains just an untyped project directory—but recommended.Generic source roots refer to top-level directories containing project files. The contents of the *Files* tab is determined by these.Typed source roots refer to particular directories (which should be inside, or equal to, some generic source root) used for particular purposes. For exam [...]
+`SharabilityQueryImplementation`:: Optionally lets the project declare that certain folders (or, perhaps, files) are not intended for sharing with other users, typically in a version control system. If your project type defines a build folder, or a folder containing private data (such as file paths on the developer’s local disk), marked in unsharable. The IDE’s VCS integration can use this information to avoid trying to commit such folders to VCS. Other IDE features may use this informat [...]
+`RecommendedTemplates`:: Optionally define categories of file templates that this project type should allow to be added. For example, a J2ME-oriented project type would probably want to exclude Swing forms and servlets, but permit MIDlets.
+`PrivilegedTemplates`:: Defines a set of specific templates that are likely to be important to users of the project type. Used to create the default *New* submenu in the project’s context menu.
+
+
+[[Building_and_Other_Actions]]
+=== Building and Other Actions
+
+Most project types will have some kind of actions which can be performed on the project: build it, run some program it represents, etc.
+
+`ActionProvider`:: A simple interface used to specify how certain “standard”
+actions like *Build* should behave when applied to your project (e.g. from the
+IDE’s toolbar). Such actions might run an Ant target, for example.Note that you
+do not need to include mappings in `ActionProvider` which will be used only
+from GUI your module provides itself. For example, you can add context menu
+items to your project’s node that perform additional actions without going
+through `ActionProvider.` This interface exists to permit GUI coöperation
+between your project and the rest of the IDE. `FileBuiltQueryImplementation`::
+If some files have a source representation and can be somehow processed
+individually into “built” or “compiled” versions, you want to add a
+`FileBuiltQueryImplementation` to represent this fact. Currently only `*.java`
+files make use of `FileBuiltQuery`, to show an out-of-date badge, though nodes
+for other file types could be extended to do so in the future as well.
+
+
+[[Java-Specific_Behavior]]
+=== Java-Specific Behavior
+
+Several queries are used to permit integration of various Java editing and browsing features in the IDE with the project system. Any projects which deal with Java sources should try to implement these queries.
+
+`ClassPathProvider`:: Important query used to specify the class path used for a Java file or source root. Without this query, much important functionality will be broken, e.g. completion in the source editor and refactoring. See its Javadoc for details on usage.
+`SourceLevelQueryImplementation`:: Also important—instructs the editor, parser, and other IDE components what Java source level to use for a file. For example, assertions will only be recognized if the level is at least `1.4`, and generics only if at least `1.5`.
+`SourceForBinaryQueryImplementation`:: Also an important query, as it is needed for source stepping when debugging, interproject dependencies, and other purposes. If your project’s Java sources are ever compiled to some build directory, and perhaps packed into JARs after that, you must implement this query in order for other parts of the IDE to understand where to find sources corresponding to the build product.
+`JavadocForBinaryQueryImplementation`:: Important if you ever produce or bundle Javadoc in your project. This query enables Javadoc search to work correctly when someone is depending on classes from your project.
+`UnitTestForSourceQueryImplementation`:: Helpful to implement in case you have unit tests in your project (typically in JUnit format). The JUnit support module will then be able to properly configure some wizards and actions.
+
+
+[[Project_Dependencies]]
+=== Project Dependencies
+
+`SubprojectProvider`:: If you have a formal way of representing “subprojects” of your project—which might be projects physically packaged into your project, or located inside it on disk, or just used by it at build time, etc.—you can enumerate them with this interface. This is optional and is currently only used for the subproject list in the *Open Project* dialog (subprojects may be opened automatically) and for `CommonProjectActions.openSubprojectsAction`.
+
+
+[[Miscellaneous]]
+=== Miscellaneous
+
+`ProjectOpenedHook`:: You can perform various kinds of special actions when your project is being opened or closed _in the GUI_. Remember that your project can be loaded in memory without being open, and is expected to function reasonably anyway. The Javadoc mentions various typical actions you might perform here.
+`AuxiliaryConfiguration`:: Strongly recommended to implement if possible. Permits foreign code to store extra metadata inside your project, in XML format. Used for example to store files open in the editor from a project, and editor bookmarks.
+`CacheDirectoryProvider`:: Also recommended to implement though not yet in use. Permits foreign code to store cache files associated with your project.
+
+
+[[How_to_Write_an_Ant-Based_Project_Type]]
+== How to Write an Ant-Based Project Type
+
+While a project can be written directly to the bare SPIs such as `ProjectFactory` and various interfaces (such as `SubprojectsProvider`) placed into project lookup, you may wish to reuse the basic Ant-based project infrastructure used by most IDE project types. This support SPI conveys several major benefits:
+
+* You do not need your own `ProjectFactory`; any folder containing a file `nbproject/project.xml` containing a project type identifier you choose will be recognized as yours. The project load and save cycle is managed for you.
+* There is support for storing project metadata in structured ways, such as in `nbproject/project.xml` or `nbproject/project.properties`. For properties-based storage it is possible to load and evaluate multiple properties files in a rich way, and listen to dynamic changes in properties-based configuration.
+* There is direct support for managing Ant builds (of course). You can have build script(s) generated based on `project.xml` and an XSLT stylesheet you provide. This is usually used to make an `nbproject/build-impl.xml` file containing default build steps and imported from an editable `build.xml`.
+* There are default implementations of various queries and other interfaces needed for your lookup, such as `Sources`, loading configuration from properties files (shared by the Ant script) where appropriate.
+* It is possible to manage references to files (such as libraries) or other projects in a structured way, with a predefined storage format, automatic synchronization to properties files, enumeration of subprojects, and a default GUI for resolving broken references.
+
+The following sections describe what steps you need to take in order to write an Ant-based project type, in addition to or instead of steps taken for general project types.
+
+For a complete example of an Ant-based project type you may wish to look at the implementation of the “general Java project” type, located in netbeans.org CVS under `java/j2seproject/` (link:http://www.netbeans.org/source/browse/java/j2seproject/[browse online]).
+
+
+[[Deciding_on_a_Source_Layout]]
+=== Deciding on a Source Layout
+
+Ant-based projects always have an `nbproject` subdirectory in the project directory with a file `nbproject/project.xml` which identifies the project and can contain some metadata. Typically there are several other files in standard locations. See the [design.html#project-layout design document] for an overview of the general Ant-based project layout if you are not yet familiar with it, and study some actual project in the IDE such as a plain Java library project.
+
+Now think about layout details specific to your project type. Perhaps you want to add another properties file for some unforeseen reason; this is up to you (almost all of the Ant-based project infrastructure classes will work happily with such a setup, except perhaps for `ReferenceHelper`, described below). Certainly you will want to decide what kinds of source files reside where and in what structure. For example, for a plain Java project, the specifics of the structure are:
+
+1. main Java sources in `${src.dir}`, default `${basedir}/src` or an external root; may be more than one such source directory
+. (optional) unit test sources in `${test.src.dir}`, default `${basedir}/test` or an external root; again, may be more than one such directory
+. (optional) JAR manifest in `${manifest.file}`, default `${basedir}/manifest.mf`
+. `${build.dir}` (default `${basedir}/build`) holds various transient build products (e.g. compiled classes not yet packed into a JAR)
+. `${dist.dir}` (default `${basedir}/dist`) holds the finished JAR as well as any generated Javadoc. Furthermore, you need to decide what project metadata you will store. This includes the structure of `project.xml` (and perhaps `private.xml` if you need to use it for anything), as well as a list of recognized keys and their semantics for `project.properties` and/or `private.properties`. For example, for a plain Java project, `project.xml` can specify:
+.. the project name
+.. a list of source roots (giving in each case the name of the Ant property specifying its actual location)
+.. the minimum Ant version needed to build (probably `1.6`)
+.. (optional) an explicit platform marker indicating that the build should refer to a particular JDK
+
+These decisions are codified in an XML schema for the `project.xml` file (link:http://www.netbeans.org/ns/j2se-project/2.xsd[example]). Currently the schema is not used for runtime validation, but that is expected to change; in the meantime, you are strongly recommended to define a schema to make sure you have clearly defined what can and cannot be stored in `project.xml`.
+
+Your project type does not directly control the whole `project.xml` file. Rather, the Ant-based infrastructure will manage loading, parsing, and saving it, using APIs to be described below; and you only control one section of it, called the primary configuration data. You need to select an XML element name and namespace that will identify this block. For example, general Java projects use an element `<data xmlns="link:http://www.netbeans.org/ns/j2se-project/2[http://www.netbeans.org/ns/j [...]
+
+You also need to define a primary configuration data block name for `private.xml` in the `nbproject/private/` folder, whether or not you plan to write anything to this file. For example, general Java projects use `<data xmlns="link:http://www.netbeans.org/ns/j2se-project-private/1[http://www.netbeans.org/ns/j2se-project-private/1]">`. You can just define an empty schema for this block that allows no content (link:http://www.netbeans.org/ns/j2se-project-private/1.xsd[example]), or you can [...]
+
+Also related to `project.xml`, you need to pick a project type identifier. This is just a short string—it could be the code name base of your module—which uniquely identifies your project type. This will be stored in the `<type>` element at the top of `project.xml`.
+
+A Java project can likewise use a number of different Ant properties, such as `src.dir`, `main.class`, `javac.classpath`, `run.jvmargs`, etc. *(XXX link to spec when available)* You will need to decide what properties your project type will recognize and what the values should mean, while working on the build script (below).
+
+
+[[Writing_a_Prototypical_Build_Script]]
+=== Writing a Prototypical Build Script
+
+Make a prototype of a real project—it does not need to be loadable by the IDE as a project yet, just have realistic source files and be buildable by Ant (either from the command line or through the IDE using e.g. the *Favorites* node). Write an empty `build.xml`:
+
+[source,xml,subs="{markup-in-source}"]
+----
+<project name="x" default="choose-something" basedir=".">
+ <import file="nbproject/build-impl.xml"/>
+</project>
+----
+
+And write an `nbproject/build-impl.xml` that does the various build steps you would like the project to do. Generally it should load some properties files first, e.g.
+
+[source,xml,subs="{markup-in-source}"]
+----
+<project name="x-impl" basedir=".."> <!-- note basedir is project directory -->
+ <target name="-pre-init"><!-- placeholder --></target>
+ <target name="-init-private" depends="-pre-init">
+ <property file="nbproject/private/private.properties"/>
+ </target>
+ <target name="-init-user" depends="-init-private">
+ <property file="${user.properties.file}"/>
+ </target>
+ <target name="-init-project" depends="-init-user">
+ <property file="nbproject/project.properties"/>
+ </target>
+ <target name="-init" depends="-init-project">
+ <!-- maybe some other stuff... -->
+ </target>
+ <!-- now normal targets... -->
+</project>
+----
+
+Note that it is conventional to begin the names of “internal” targets that should not be run directly (only as dependencies) with a hyphen (-).
+
+Think about which targets the user should override in `build.xml` for what purpose. It is nice to put in “placeholder” targets which by default do nothing but which can easily be overridden to insert some custom steps at a certain point in the build.
+
+
+[[Selecting_Ant_Tasks]]
+==== Selecting Ant Tasks
+
+Which Ant tasks are available to you? Naturally you are free to use any standard Ant task which comes with the Ant distribution and does not require a special library to run. (Make sure you decide which version of Ant your scripts will require at a minimum—generally this will be the version currently shipped with the IDE. Later versions should work as well.) However some other tasks may require a bit of special setup. In particular:
+
+Bundled optional tasks requiring special libraries:: Some tasks come with Ant but require a special library in order to run. In the current design of Ant, these can only be run if the IDE includes the library directly in Ant’s main classpath. For example, the `<junit>` task runs inside the IDE without any user setup because the `org.netbeans.modules.junit` module requests that `junit.jar` be added to Ant’s classpath. Other modules may request such classpath additions by implementing `Aut [...]
+Non-bundled custom tasks:: You may wish to have your project’s build script run some Ant tasks which do not ship with Ant. (Do so only when really required, because it is annoying to users to have their build infrastructure depend on special things.) Some module (perhaps your project type module, perhaps not) must supply the task definition JAR(s):
+
+
+1. Make sure the task JAR, as well as any special libraries it may need, is installed in the IDE distribution by including it in the module’s NBM file.
+. Define a project library of type `j2se` and place it in the `org-netbeans-api-project-libraries/Libraries/` folder of your module XML layer. Example definition (see the Project Libraries API for more details):
+
+[source,xml,subs="{markup-in-source}"]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE library PUBLIC
+ "-//NetBeans//DTD Library Declaration 1.0//EN"
+ "link:http://www.netbeans.org/dtds/library-declaration-1_0.dtd[http://www.netbeans.org/dtds/library-declaration-1_0.dtd]">
+<library version="1.0">
+ <name>mytasks</name>
+ <type>j2se</type>
+ <localizing-bundle>org.netbeans.modules.thismodule.Bundle</localizing-bundle>
+ <volume>
+ <type>classpath</type>
+ <resource>jar:nbinst://org.my.module.name/ant/extra/mytasks-1.2.3.jar!/</resource>
+ </volume>
+</library>
+----
+
+
+
+. Now `build.properties` in the user directory will be populated with the actual path to the library, so you can use it in your build script:
+
+[source,xml,subs="{markup-in-source}"]
+----
+<target name="-init-taskdefs" depends="-init">
+ <!-- Assumes 1.6-style antlib is present: -->
+ <taskdef resource="org/netbeans/mytasks/antlib.xml" uri="antlib:org.netbeans.mytasks">
+ <classpath>
+ <pathelement path="${libs.mytasks.classpath}"/>
+ </classpath>
+ </taskdef>
+</target>
+<target name="use-taskdefs" depends="-init-taskdefs">
+ <mytask xmlns="antlib:org.netbeans.mytasks" someattr="true"/>
+</target>
+----
+
+You could also manually update `build.properties` using `PropertyUtils` to define some other property name not using the `libs._name_.classpath` format, e.g. when your project type module is restored or a project of your type is opened. Using the library manager is easier because `build.properties` is managed for you.If you wrote the task(s) for this purpose, you are _strongly recommended_ to make task source code available as open source (e.g. under the Sun Public License), so that user [...]
+
+In-VM tasks present in existing modules:: NetBeans has the ability to run special Ant tasks which interact with other parts of the IDE (and cannot be run outside the IDE). A few commonly required tasks ship with the IDE; if you want to use them, declare a dependency on the module which defines them. You can refer to the tasks by simple name, but when using Ant 1.6+ it is preferable to use the correct “antlib” namespace. (Note that when prototyping a build script you can use the IDE’s cod [...]
+Web browser integration (`antlib:org.netbeans.modules.browsetask)`:: `<nbbrowse>` lets you open the IDE’s configured web browser on a given URL (or file).
+JPDA debugger integration (`antlib:org.netbeans.modules.debugger.jpda.ant`):: `<nbjpdastart>` asks the IDE’s debugger to start listening on a new JPDA port, and define an Ant property with the port so you can launch a Java process which will connect to that port as a client. `<nbjpdaconnect>` connects to an existing port; more useful for server applications. `<nbjpdareload>` reloads Java classes using “fix & continue” technology.
+Custom in-VM tasks:: You can also define your own in-VM tasks and use them the same way as the predefined ones. See the link:https://bits.netbeans.org/dev/javadocAntModuleAPI/org/apache/tools/ant/module/spi/package-summary.html#register-defs[Ant SPI] for details.
+
+
+[[Parametrizing_Build_Scripts]]
+=== Parametrizing Build Scripts
+
+Some project types have several variants for `build-impl.xml`, parametrized somehow. For example, plain Java projects behave a little differently depending on whether you are building and running against the “default platform” (the IDE’s own JDK) or an explicit JDK. The former case might look like (excluding irrelevant details):
+
+[source,xml,subs="{markup-in-source}"]
+----
+
+<target name="compile">
+ <javac srcdir="..." destdir="..." classpath="..."/>
+</target>
+----
+
+whereas the latter case might look like:
+
+[source,xml,subs="{markup-in-source}"]
+----
+
+<target name="compile">
+ <javac srcdir="..." destdir="..." classpath="..." fork="true" executable="..."/>
+</target>
+----
+
+The rule of thumb here is simple. _If some aspect of the build can be parametrized using Ant properties in a straightforward way using the Ant tasks you have available, do so._ For example, there is no need to create a different `build-impl.xml` just to change the build directory; this can be done using a property:
+
+[source,xml,subs="{markup-in-source}"]
+----
+
+<target name="compile">
+ <javac srcdir="..." destdir="${build.classes.dir}" classpath="..."/>
+</target>
+----
+
+But in other cases, this is not possible. For example, Ant’s `<junit>` task can take a `jvm` attribute to specify an explicit JDK to run against. If you include this attribute, you have to set the JDK. When using the default platform, this attribute must not be there; when using an explicit platform, it must be there. Therefore `build-impl.xml` needs to be a bit different in these two cases (unless you included both versions in different targets and switched between them at runtime, thou [...]
+
+Now to go back to `project.xml` for a moment: whatever variations in `build-impl.xml` you wish to support must be codified as metadata in `project.xml`. For example, a plain Java project can include an `<explicit-platform>` element or not; the presence or absence of this element determines which `build-impl.xml` variant is produced.
+
+
+[[Writing_Stylesheets]]
+=== Writing Stylesheets
+
+When you are satisfied with the `build-impl.xml` you have drafted (perhaps in multiple variants), it is time to write an link:http://www.w3c.org/TR/xslt[XSLT stylesheet] which produces it. The input to the stylesheet is the `project.xml` file and the output is the build script. Typically you will just copy most of the prototype build script verbatim into the stylesheet as the default content. You will also want to examine the `project.xml` input at least for a project name, and optionall [...]
+
+[source,xml,subs="{markup-in-source}"]
+----
+
+<project xmlns="link:http://www.netbeans.org/ns/project/1[http://www.netbeans.org/ns/project/1]">
+ <type>org.netbeans.modules.myprojecttype</type>
+ <configuration>
+ <data xmlns="link:http://www.netbeans.org/ns/my-project-type/1[http://www.netbeans.org/ns/my-project-type/1]">
+ <name>Test Project</name>
+ <style>first</style> <!-- whatever this means to you -->
+ </data>
+ </configuration>
+</project>
+----
+
+You might have a stylesheet like this:
+
+[source,xml,subs="{markup-in-source}"]
+----
+
+<xsl:stylesheet version="1.0"
+ xmlns:xsl="link:http://www.w3.org/1999/XSL/Transform[http://www.w3.org/1999/XSL/Transform]"
+ xmlns:p="link:http://www.netbeans.org/ns/project/1[http://www.netbeans.org/ns/project/1]"
+ xmlns:xalan="link:http://xml.apache.org/xslt[http://xml.apache.org/xslt]"
+ xmlns:myproj="link:http://www.netbeans.org/ns/my-project-type/1[http://www.netbeans.org/ns/my-project-type/1]"
+ exclude-result-prefixes="xalan p myproj">
+ <xsl:output method="xml" indent="yes" encoding="UTF-8" xalan:indent-amount="4"/>
+ <xsl:template match="/">
+ <xsl:comment><![CDATA[
+*** GENERATED FROM project.xml - DO NOT EDIT ***
+*** EDIT ../build.xml INSTEAD ***
+]]></xsl:comment>
+ <xsl:variable name="name" select="/p:project/p:configuration/myproj:data/myproj:name"/>
+ <xsl:variable name="codename" select="translate($name, ' ', '_')"/>
+ <project name="{$codename}-impl" basedir="..">
+ <!-- ... -->
+ <target name="shows-variants">
+ <xsl:variable name="style" select="/p:project/p:configuration/myproj:data/myproj:style"/>
+ <xsl:choose>
+ <xsl:when test="$style = 'first'">
+ <do-one-thing-in-ant/>
+ </xsl:when>
+ <xsl:when test="$style = 'second'">
+ <do-another-thing-in-ant/>
+ </xsl:when>
+ <xsl:otherwise>
+ <!-- error -->
+ </xsl:otherwise>
+ </xsl:choose>
+ </target>
+ </project>
+ </xsl:template>
+</xsl:stylesheet>
+----
+
+_Remember_ that { and } in attribute values have a special meaning in XSLT: if you want to use braces literally, e.g. for Ant property references, double them, e.g.
+
+[source,xml,subs="{markup-in-source}"]
+----
+
+<!-- this is in XSLT: -->
+<target name="something">
+ <mkdir dir="${{build.classes.dir"/>
+ <!-- ... -->
+</target>
+----
+
+You will also want a stylesheet to generate `build.xml`, though typically this is quite simple:
+
+[source,xml,subs="{markup-in-source}"]
+----
+<xsl:stylesheet version="1.0"
+ xmlns:xsl="link:http://www.w3.org/1999/XSL/Transform[http://www.w3.org/1999/XSL/Transform]"
+ xmlns:project="link:http://www.netbeans.org/ns/project/1[http://www.netbeans.org/ns/project/1]"
+ xmlns:myproj="link:http://www.netbeans.org/ns/my-project-type/1[http://www.netbeans.org/ns/my-project-type/1]"
+ xmlns:xalan="link:http://xml.apache.org/xslt[http://xml.apache.org/xslt]"
+ exclude-result-prefixes="xalan project myproj">
+ <xsl:output method="xml" indent="yes" encoding="UTF-8" xalan:indent-amount="4"/>
+ <xsl:template match="/">
+ <xsl:comment> You may freely edit this file. See commented blocks below for </xsl:comment>
+ <xsl:comment> some examples of how to customize the build. </xsl:comment>
+ <xsl:comment> (If you delete it and reopen the project it will be recreated.) </xsl:comment>
+ <xsl:variable name="name" select="/project:project/project:configuration/myproj:data/myproj:name"/>
+ <xsl:variable name="codename" select="translate($name, ' ', '_')"/>
+ <project name="{$codename}">
+ <xsl:attribute name="default">default</xsl:attribute>
+ <xsl:attribute name="basedir">.</xsl:attribute>
+ <description>Builds, tests, and runs the project <xsl:value-of select="$name"/>.</description>
+ <import file="nbproject/build-impl.xml"/>
+ <xsl:comment><![CDATA[
+ You could add descriptions of overridable targets here, or just link to online help...
+ ]]></xsl:comment>
+ </project>
+ </xsl:template>
+</xsl:stylesheet>
+----
+
+You can fine-tune the XSLT for your build scripts, as well as the `project.xml` format and the list of Ant properties you want to recognize, _without writing one line of NetBeans module source code_. (Just run `project.xml` through your stylesheets to see the output, using any XSLT tool, such as that built into the NetBeans IDE.) All you are doing at this stage is defining some metadata for the project and verifying that Ant scripts generated from it do indeed build and run an example pr [...]
+
+
+[[Writing_the_Project_Type_Skeleton]]
+=== Writing the Project Type Skeleton
+
+Now it is time to begin writing the project type provider module proper. First you will need an implementation of `AntBasedProjectType` which registers your project type in the system. (Place this implementation in default lookup, e.g. using the `META-INF/services/` section of your module JAR.) The project type class does not do much except report the project type identifier, and the local name and namespace used for the shared and private primary configuration data blocks (in `project.x [...]
+
+You will need a separate class for the `Project` implementation, which will usually hold onto the instance of `AntProjectHelper` and use it to service requests.
+
+Another common thing to set up in your project’s constructor is a property evaluator, which can load the current values of various properties from `project.properties`, `private.properties`, and `build.properties`, using Ant’s property evaluation semantics, and notify you of changes even in specific properties. A `PropertyEvaluator` instance is also a required parameter for many convenience factory methods and constructors in the Ant-based project support. Many projects can just call `An [...]
+
+The project should create a `Lookup` containing its particular abilities and return this from the `getLookup()` method. Normally `Lookups.fixed` is adequate for this purpose. In principle a project’s lookup could change dynamically, but this is not normally required. More information on what to put in the lookup can be found below.
+
+
+[[Handling_Build_Script_.28Re-.29generation]]
+=== Handling Build Script (Re-)generation
+
+The normal way that `build.xml` and `build-impl.xml` are created is that these files are automatically generated whenever they are missing; and regenerated when they are out of date relative to the current XSLT stylesheet and `project.xml`, _but_ not modified by the user. (`private.xml` is not considered: since it is per-user, the shared build script cannot be changed according to its contents.) Note that `build-impl.xml` is not _supposed_ to be modified by the user, but at least if it i [...]
+
+To configure the normal (re-)generation semantics, make sure your project’s lookup contains:
+
+
+
+. A `ProjectXmlSavedHook`, used when `project.xml` is modified and saved.
+. A `ProjectOpenedHook`, used when the project is opened.
+
+The Javadoc for `GeneratedFilesHelper.refreshBuildScript` describes the recommended parameters that should be passed to it from these two hooks. Remember that your XSLT stylesheets should be packaged in the module JAR so they can be passed to this method.
+
+Other kinds of behavior are possible; check the `GeneratedFilesHelper` Javadoc for more information. You could also produce Ant build scripts using some method other than XSLT transformations (e.g. manual DOM manipulation), but `GeneratedFilesHelper` will not currently (#42735) help you determine whether the scripts are modified or out of date if you do this, so you would need to write this logic yourself.
+
+
+[[Populating_the_Project_Lookup]]
+=== Populating the Project Lookup
+
+*PENDING*
+
+
+[[Creating_a_Properties_Dialog]]
+== Creating a Properties Dialog
+
+*PENDING*
+
+
+[[Handling_Upgrades]]
+== Handling Upgrades
+
+*PENDING*
+
+
+[[How_to_Use_Project-Related_APIs_from_Other_Modules]]
+== How to Use Project-Related APIs from Other Modules
+
+*PENDING*
+
+
+[[Some_Interesting_Things_which_are_Impossible]]
+== Some Interesting Things which are Impossible
+
+There is no general API for accessing project settings from the outside, and anyway it comes in various forms depending on the particular project type. For example, J2SE projects currently let you configure a main class, a working directory, etc. These things make no sense for web applications. Conversely, context root is critical for a web application but senseless for a J2SE project. There are no plans to ever have a general API for accessing this kind of project configuration from the [...]
+
+Someday there may be an SPI for plugging in natures (behaviors for a project), in response to accumulated feedback and experience from people trying to do this sort of thing (e.g. the JFluid project); currently there are no plans for it. The project type is currently expected to directly handle all of the significant build/run scenarios which it could support, such as running, debugging, and unit testing.
+
+Currently the JFluid module accomplishes its profiler integration for a fixed list of known project types by relying on knowledge of the disk layout and file formats of those project types, and either running the app directly based on settings read in this way, or generating auxiliary Ant scripts in `nbproject/` which can launch the app with specialized parameters in addition to the normal properties-file-based settings.
+
+Note that you can use e.g. `ClassPath.getClassPath(FileObject)` to find various classpaths which the project claims it uses to build or run the app. How the project actually builds or runs the app is its own business; the API-exposed information is intended for use in code completion, refactoring, and similar development-time-only features, and is intentionally the bare minimum information required for these features. For example, getting the classpath for a _particular_ source root cont [...]
+
+
+[NOTE]
+====
+
+The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/BuildSystemHowTo[http://wiki.netbeans.org/BuildSystemHowTo] , that was last modified by NetBeans user Jglick on 2010-02-19T17:17:47Z.
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/CompatibilityPolicy.asciidoc b/netbeans.apache.org/src/content/wiki/CompatibilityPolicy.asciidoc
new file mode 100644
index 0000000..50cea07
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/CompatibilityPolicy.asciidoc
@@ -0,0 +1,245 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+
+= CompatibilityPolicy
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:jbake-status: published
+:syntax: true
+:description: Compatibility Policy
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:toclevels: 5
+:experimental:
+
+== Introduction
+
+We have long had a general link:VersioningPolicy.asciidoc[VersioningPolicy]
+describing how to maintain APIs and make compatible changes. There was also a
+note on making incompatible changes but it did not cover any real policy.
+
+
+[[Types_of_incompatible_change]]
+== Types of incompatible change
+
+There are several basic grades of incompatible API changes, from mild to severe in effects.
+
+
+[[Separable]]
+=== Separable
+
+Sometimes an entire class can be deprecated
+so that no one need refer to it any more when using the new recommended API.
+This is generally possible when the class contains either static utility code or an old SPI,
+but is not directly referred to from other (non-deprecated) API classes.
+We can call such an API _separable_ and changes to such APIs are relatively straighforward.
+
+When a whole class is deprecated, it is best to move this class to a deprecated module.
+Over time we can collect deprecated classes and safely package them up.
+A link:http://bits.netbeans.org/dev/javadoc/org-openide-modules/org/openide/modules/doc-files/api.html#deprecation[deprecated module]
+is marked with `OpenIDE-Module-Deprecated: true`
+and can include a localizable `OpenIDE-Module-Deprecation-Message` as well.
+
+You can use the link:http://bits.netbeans.org/dev/javadoc/org-openide-modules/org/openide/modules/doc-files/api.html#refactoring[module refactoring facility]
+to retain binary compatibility for old client modules still referring to the class
+in its original module.
+They can migrate on their own schedule.
+The deprecated module can be made an autoload so it is not enabled in a standard IDE distribution,
+and eventually we can move it to the Update Center and out of the standard codebase.
+
+Non-Java-language APIs can sometimes fall into this category as well.
+For example, a deprecated style of object registration could in some cases be supported only when a deprecated module is enabled,
+without cluttering the code which handles the new style of registration.
+
+In some cases it is necessary to create bridges, especially in case of SPI parts of this API.
+as analyzed link:http://wiki.apidesign.org/wiki/Evolving_the_API_Universe[elsewhere],
+this is tricky yet possible.
+
+
+[[Phased]]
+=== Phased
+
+Many deprecated APIs cannot be easily separated without causing an incompatible API change and breaking old clients at some point.
+For example, a central class like `FileObject` cannot realistically be replaced with something else:
+far too many other APIs refer directly to `FileObject` in method signatures,
+and published NetBeans Platform documentation makes frequent reference to this class.
+However, certain methods like `getPackageName` (meaningless as of NB 4.0)
+can be deprecated and eventually deleted once everyone has had ample time to stop using them.
+
+To quote the
+link:http://java.sun.com/javase/6/docs/technotes/guides/javadoc/deprecation/deprecation.html[Java guide],
+deprecation is used when an API
+
+* is insecure, buggy, or highly inefficient;
+* is going away in a future release;
+* or encourages bad coding practices.
+
+Most deprecations will involve the actual `@Deprecated` annotation.
+(The `@deprecated` Javadoc tag should be used as well,
+to give instructions on what to do instead.)
+In some cases, an API involves a non-Java-language construct yet needs to be deprecated;
+for example, placement of XML layer entries into the wrong folder.
+In these cases, platform code should issue a warning into the log file
+noting the problem, the source (culpable module), and suggested fix.
+
+
+[[Historical_policy]]
+==== Historical policy
+
+Prior to this writing (NB 6.5) we have not had a general policy on incremental incompatible changes.
+As a result we were afraid of breaking anything by doing incompatible changes,
+which often resulted in the extreme position of never deprecating old, obsoleted ways of doing certain tasks.
+The result was that:
+
+* New API users can become overwhelmed trying to find what code patterns are actually encouraged, making the Platform seem overly complex and hard to learn. (`getLookup`? `getCookie`? `getCookieSet`? ...)
+* Nobody fixes obsoleted API usages even in our own codebase, which results in additional accumulation of usages of such APIs due to infamous, yet common, "copy-paste programming".
+* Old usages of obsoleted APIs are not reported to developers when they migrated to a new version of the platform.
+
+This resulted in the accumulation of old debris in many central APIs
+(some of it formally marked `@Deprecated`, some not).
+Moreover, even if such APIs became formally deprecated,
+the general injunction of not breaking backward compatibility
+resulted in keeping this debris around, some of it likely unused for years.
+The presence of this much deprecated code in our APIs has several ill effects
+for users of the NetBeans Platform, as well as NetBeans API developers:
+
+* Modules are bloated by unused bytecode, and module projects by unused source code.
+* In many cases non-deprecated code has to explicitly accommodate the existence of deprecated code, increasing complexity and thus maintenance burden and likelihood of bugs.
+
+Of course, these ill effects have to be balanced in each case by the benefit to the maintainer of a client module in having the API left untouched.
+For example, an isolated static utility method of small size does not do much harm to the containing API,
+whereas if it was at one time heavily used,
+deleting the method could cause a lot of trouble for third-party module developers.
+
+
+[[Proposed_policy]]
+==== Proposed policy
+
+When deprecating an inseparable API in a phased manner,
+the author of the replacement API is responsible for making sure
+that the usage of obsoleted predecessor is eliminated from the NetBeans.org code base
+in a timely manner, or properly justifying why that need not happen.
+
+It is proposed that after an inseparable API (class with outside references, method, ...)
+has been officially deprecated in a major NetBeans release,
+and was not in fact used by any modules present in that release,
+that it is permitted to be hidden from newly compiled sources (via `PatchedPublic` annotation) in the next release and then deleted completely in a subsequent one. Note that "major release" in this context does not refer to the version of NetBeans (e.g. NetBeans 5.5, 5.5.1, 6.0, etc.) but rather a change of enough signficance to warrant incrementing the cluster's version number (e.g. platform8, platform9, etc.).
+
+The simplest variant is that the API can be hidden from newly compiled clients in the very next major release after its deprecation: a one-release grace source compatibility period. This may be considered too aggressive, however this is balanced by keeping the binary compatibility for yet another release: a two-release binary compatibility grace period, meaning the API must must exist for linkage (not compilation and unused) for at least two major releases
+before it can be deleted in a third. Of course, it is important to _announce_ the expected time of hiding/deletion
+before the grace period begins.
+
+The rest of this section describes the details of how such a policy could be implemented.
+Feedback from community members (mainly third-party module developers)
+is very much needed.
+
+This process also needs to be integrated with link:BackwardCompatibilityTesting.asciidoc[BackwardCompatibilityTesting].
+
+
+[[Technical_procedure_for_making_an_incompatible_phased_change]]
+==== Technical procedure for making an incompatible phased change
+
+1. Introduce the replacement API which is intended to cover all use cases covered by the old API.
+. Mark the old API as deprecated. Properly document the intended replacement.
+. Whenever possible, create an editor hint to identify usages of the deprecated API; and, in case there is a mechanical correspondence with the new API, also offer an automated fix for converting to the new idiom.
+. Take responsibility for replacing all usages of the old API in modules hosted on netbeans.org. (Include the `main` and `contrib` repositories at least.)
+. Directly fix everything you can safely and confidently change yourself.
+. File P2 defects for what you cannot fix yourself, because the surrounding code is too subtle and unfamiliar. Be ready to provide advice to the assignee of the bug. Keep track of all such bugs using Issuezilla dependencies.
+. Try to finish the transition within a single development cycle. (If you cannot do so, consider seriously whether you can expect third-party module developers to do the same!)
+. If you find that the proposed replacement does not cover every use case after all, you need to either fix that immediately or defer the deprecation until you can.
+. Increment the major release version of the API module, unless this has already been done for another phased change in the same module in the same release cycle.
+. Announce timing of the expected deletion in your `apichanges.xml` entry. (You must have finished the replacement in netbeans.org modules _first_.)
+. In next _major_ release, make the source-incompatible, yet binary compatible change. (Make the method/field/class private and annotate it with `@org.openide.modules.PatchedPublic`. Any client wishing to recompile cannot use the method any more.)
+. In the next _major_ release, remove the private API.
+
+
+[[Versioning_impact]]
+==== Versioning impact
+
+The module system supports _ranges_ in the major release version used in a module dependency.
+For example, `org.openide.filesystems/1-2 > 7.42` means that this module should be compatible
+with `org.openide.filesystems/1` in version 7.42 or later,
+or any version of `org.openide.filesystems/2`,
+but perhaps not with `org.openide.filesystems/3` or higher.
+If we had a consistent expectation for the _minimum_ grace period used for incompatible changes,
+then we could use ranges to good effect to preserve binary compatibility during the grace period.
+
+For example, assuming a one-release grace period,
+any module which compiled without deprecation warnings against `org.openide.filesystems/1`
+(and which produced no runtime warnings in the log)
+could safely declare `org.openide.filesystems/1-2 > ...` as its dependency.
+The module would then be usable without recompilation in the subsequent NetBeans release,
+making it easier to evaluate possible migration to a new release,
+and relieving the maintainer of the need to supply an update to users the moment the new release came out.
+
+TBD whether it makes sense for the module development support to automatically introduce ranges like this when adding a module dependency to a project.
+The use of the range makes sense only if the developer is really committed to avoiding _all_ usage of deprecated elements from the API.
+
+
+[[Open_issues]]
+==== Open issues
+
+The minimum grace period before deletion acceptable to the community needs to be determined. So far:
+
+1. one major release for deprecating and remove usage from netbeans.org modules
+. one major release for source-incompatible, yet binary-compatible change via `PatchedPublic` annotation
+. removal in subsequent major release
+
+`apichanges.xml` needs a new syntax for an incompatible phased change with expected removal date/release. The existing `incompatible` option is a bit misleading here.
+
+IDE/Platform release notes should link to this policy (or a summary of it),
+as well as the API change list,
+and should be reviewed for readability and accuracy
+by a qualified documenter (gwielenga comes to mind).
+
+
+[[Abrupt]]
+=== Abrupt
+
+On occasion some part of an API, or a whole API, simply needs to be replaced with something quite different.
+In such a case there needs to be a "flag day" when all usages of the old API are replaced
+with the new API (or simply removed from the build or commented out).
+
+For example, there was no plausible way to migrate smoothly from the 3.6 Filesystems-as-classpath paradigm to the 4.0 project system;
+nor from the MDR/JMI/Javamodel system to the "Retouche"/javac system.
+
+Clearly such a major change has to be planned and communicated well in advance.
+Anyone wishing to migrate to the new version of NetBeans has to adapt their code.
+
+If there is a policy of using major release version ranges to accommodate planned deletions of deprecated APIs (see above),
+then abrupt incompatible changes would need to be accompanied by increments of the major release version of the API module by 2 or more
+(i.e., one more than the minimum grace period length).
+
+
+[NOTE]
+====
+
+The content in this page was kindly donated by Oracle Corp. to the
+Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/CompatibilityPolicy[http://wiki.netbeans.org/CompatibilityPolicy] ,
+that was last modified by NetBeans user Jglick
+on 2010-06-18T15:24:35Z.
+
+
+This document was automatically converted to the AsciiDoc format on 2020-03-15, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/Filter_Menu.png b/netbeans.apache.org/src/content/wiki/Filter_Menu.png
new file mode 100644
index 0000000..6ef320e
Binary files /dev/null and b/netbeans.apache.org/src/content/wiki/Filter_Menu.png differ
diff --git a/netbeans.apache.org/src/content/wiki/Fitness.asciidoc b/netbeans.apache.org/src/content/wiki/Fitness.asciidoc
new file mode 100644
index 0000000..277e167
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/Fitness.asciidoc
@@ -0,0 +1,73 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+= Fitness
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:jbake-status: published
+:syntax: true
+:description: NetBeans Performance Improvements
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+This is the home page for NetBeans performance work.
+
+[[Performance_Improvements]]
+== Performance Improvements
+
+For NetBeans 6.10 release the main focus is going to be on:
+
+* improving UI responsiveness and usability of the IDE during scanning (mainly navigation),
+* less intrusive detection of external file changes,
+* better diagnostics and post-mortem analysis,
+* faster debugger stepping.
+
+
+[[Press_Release]]
+=== Press Release
+
+If you wonder why we started our work with a press release, read about
+link:http://www.allthingsdistributed.com/2006/11/working_backwards.html[Working Backwards].
+
+[[Links]]
+=== Links
+
+* Measurements
+** link:FitnessMemoryLeaks.asciidoc[Fitness - Memory Leaks]
+** link:FitnessViaPartnership.asciidoc[Fitness Via Partnership]
+** link:FitnessViaPostMortem.asciidoc[Fitness Via PostMortem]
+** link:FitnessViaTimersCounter.asciidoc[Fitness Via Timers Counter]
+** link:ResourceScalability.html[ResourceScalability]
+** link:http://jupiter.czech.sun.com/wiki/view/PerformanceQE/LatestResults[Comparative dashboard]
+
+[NOTE]
+====
+The content in this page was kindly donated by Oracle Corp. to the
+Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/Fitness[http://wiki.netbeans.org/Fitness] ,
+that was last modified by NetBeans user Ashleygibbs
+on 2012-06-19T11:27:59Z.
+
+
+This document was automatically converted to the AsciiDoc format on 2020-03-14, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/FitnessMemoryLeaks.asciidoc b/netbeans.apache.org/src/content/wiki/FitnessMemoryLeaks.asciidoc
new file mode 100644
index 0000000..a55183d
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/FitnessMemoryLeaks.asciidoc
@@ -0,0 +1,155 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+
+
+= Memory Leaks need to be eliminated to Improve NetBeans Fitness
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:jbake-status: published
+:syntax: true
+:description: Memory Leaks need to be eliminated to Improve NetBeans Fitness
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:toclevels: 5
+:experimental:
+
+
+Memory leaks seem to be one area not well covered by automated test yet. That
+shall change, especially as it does not require any major changes into the
+infrastructure. Our current infrastructure
+link:http://openide.netbeans.org/tutorial/test-patterns.html#memory[assertGC]
+with cooperation of JUnit or Jemmy/Jelly tests is good enough to allow us to
+write reliable tests looking memory leaks up, providing enough info to easily
+fix them and preventing their re-appearance in the system.
+link:http://openide.netbeans.org/issues/show_bug.cgi?id=121855[issue 121855] or
+proposal for reuse of link:FitnessViaTimersCounter.asciidoc[timers/counters]
+infrastructure demonstrates the initial attempts in this area.
+
+Based on that work, this page provides a how-to tutorial of using our *Memory
+Leak Testing Infrastructure*.
+
+
+[[Who_should_do_what]]
+== Who should do what?
+
+It is unlikely to expect that other teams are going to write memory leak tests
+and that they will continuously look for memory leaks in their code. We need
+the performance team to write the tests and moreover
+write them in a way that can discover errors in foreign code. This requires
+combination of good imagination and of integration testing, however issue
+link:http://openide.netbeans.org/issues/show_bug.cgi?id=121855[issue 121855]
+shows that this is possible in principle.
+
+The *Memory Leak Testing Infrastructure* was created and is currently maintained by Jaroslav Tulach.
+
+The link:FitnessViaTimersCounter.asciidoc[probes] into production code shall be
+insert written by engineers that create the tests and either integrated
+directly, or via a patch submitted into issuezilla. The second approach needs a
+bit of presure on the module owner, so the patch is integrated in timely
+manner.
+
+The set of tests, verifying that basic create, open, edit, compile, run, close
+operations on various project types is written by Performance QE team.
+
+
+[[How_to_write_memory_leak_test]]
+== How to write memory leak test?
+
+* Well, basically write any regular test that verifies some functionality.
+* Make sure there is a link:FitnessViaTimersCounter.asciidoc[probe] inside of the tested code that reports instances that can cause memory leaks
+
+[source,diff]
+----
+File [Changed]: ProjectManager.java
+Url: http://projects.netbeans.org/source/browse/projects/projectapi/src/org/netbeans/api/project/ProjectManager.java?r1=1.38&r2=1.39
+Delta lines: +9 -1
+ -------------------
+ --- ProjectManager.java 26 Sep 2007 21:04:26 -0000 1.38
++++ ProjectManager.java 14 Dec 2007 16:11:26 -0000 1.39
+@@ -85,6 +87,8 @@
+ // XXX change listeners?
+
+ private static final Logger LOG = Logger.getLogger(ProjectManager.class.getName());
++ /** logger for timers/counters */
++ private static final Logger TIMERS = Logger.getLogger("TIMER.projects"); // NOI18N
+
+ private static final Lookup.Result<ProjectFactory> factories =
+ Lookup.getDefault().lookupResult(ProjectFactory.class);
+@@ -347,7 +351,11 @@
+ for (ProjectFactory factory : factories.allInstances()) {
+ Project p = factory.loadProject(dir, state);
+ if (p != null) {
++ if (TIMERS.isLoggable(Level.FINE)) {
++ LogRecord rec = new LogRecord(Level.FINE, "Project"); // NOI18N
++ rec.setParameters(new Object[] { p });
++ TIMERS.log(rec);
++ }
+ proj2Factory.put(p, factory);
+ state.attach(p);
+ return p;
+
+----
+
+* Before your test starts, initialize the memory leak tracking infrastructure
+
+[source,java]
+----
+ org.netbeans.junit.Log.enableInstances(Logger.getLogger("TIMER"), "Project", Level.FINEST);
+----
+
+* When your test is about to finish, assert that all collected instances can be GCed
+
+[source,java]
+----
+ org.netbeans.junit.Log.assertInstances("Some instances of Project not GCed");
+----
+
+That is all. Enjoy writing your memory leaks tests!
+
+
+[[What_to_do_when_you_find_a_memory_leak]]
+== What to do when you find a memory leak?
+
+Report an error just like
+link:http://www.netbeans.org/issues/show_bug.cgi?id=124040[124040] or
+link:http://www.netbeans.org/issues/show_bug.cgi?id=124038[124038] or
+link:http://www.netbeans.org/issues/show_bug.cgi?id=124042[124042].
+
+Add
+*PERFORMANCE* and *TEST* keywords to the issue and into status whiteboard added
+*perfleak* word, that way we will be able to list all leaks fixed in 6.1 time
+frame.
+
+
+[NOTE]
+====
+
+The content in this page was kindly donated by Oracle Corp. to the
+Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/FitnessMemoryLeaks[http://wiki.netbeans.org/FitnessMemoryLeaks] ,
+that was last modified by NetBeans user Tpavek
+on 2010-02-18T17:42:56Z.
+
+
+This document was automatically converted to the AsciiDoc format on 2020-03-15, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/FitnessViaPartnership.asciidoc b/netbeans.apache.org/src/content/wiki/FitnessViaPartnership.asciidoc
new file mode 100644
index 0000000..0dd9611
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/FitnessViaPartnership.asciidoc
@@ -0,0 +1,115 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+
+
+= FitnessViaPartnership
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:jbake-status: published
+:syntax: true
+:description: Good Tools Make Everything Simpler
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+== Good Tools Make Everything Simpler
+
+The NetBeans IDE 6.7 is here to embrace its users.
+
+The best way to do it is to establish a synergy between the NetBeans developers
+and their users/partners using the IDE. The NetBeans community has always been
+wonderful, provided a lot of valuable feedback. Moreover our community is of
+developers. We can asked them to debug, profile, and even fix, if we give them
+the right tools.
+
+We are proud to announce that the NetBeans IDE 6.7 has been enhanced with
+several self diagnostic tools to help with "in field" identification of what is
+wrong and to simplify submission for such reports to appropriate developers.
+
+
+[[Profile_The_IDE]]
+== Profile The IDE!
+
+There is a dedicated "Profile The IDE!" button in the toolbar to start, stop
+self profiling in _any distribution that includes NetBeans Profiler_.
+
+* Make sure the Performance toolbar is displayed (step 0).
+* Then click on the button to let the system start capturing thread dumps from
+the running IDE (step 1). In case the button is not visible go to Tools/Plugins
+and enable _Java Profiler_.
+* Then work in the IDE, emulate an action which seems to be slow.
+* Press the button again to turn the self profiling off (step 2).
+* The system then generates standard NetBeans Profiler IDE snapshot and shows it.
+
+Now the time has come to analyse the dump or use the "Attach IDE Snapshot to
+bug..." button to attach it
+to already existing issue.
+
+image::Profileme_FitnessViaPartnership.png["Fitness Via Partnership"]
+
+The work was meant as a joint venture of the profiler and performance teams.
+However most of the glory belongs to profiler team. It donated the sampler,
+redesigned way to convert its results into its snapshot format and also
+provided basic UI integration. The performance team encouraged that, helped
+with planning and provided emotional support.
+
+The work is useful of its own, but there is much more to be done.
+link:http://visualvm.dev.java.net[VisualVM] can benefit from the sampler as
+well. The automatic analysis of slowness can be also very helpful during
+testing and help NetBeans faster understand own performance
+problems.
+
+link:http://openide.netbeans.org/issues/show_bug.cgi?id=153[IZ 153]
+
+
+[[Am_I_Leaking]]
+== Am I Leaking!?
+
+More of link:FitnessViaTimersCounter.asciidoc[FitnessViaTimersCounters] and link:FitnessMemoryLeaks.asciidoc[FitnessMemoryLeaks].
+
+
+[[Snapshot_me]]
+== Snapshot me!
+
+In case the system throws OutOfMemory exception a file is generated to
+$userdir/var/log or similar directory and the user is asked (maybe on next
+start) to send this file to NetBeans.
+
+Requires changes to launcher to pass in additional parameter and a way to
+transfer 400MB file to issuezilla.
+
+link:http://openide.netbeans.org/issues/show_bug.cgi?id=153220[IZ 153220]
+
+
+[NOTE]
+====
+
+The content in this page was kindly donated by Oracle Corp. to the
+Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/FitnessViaPartnership[http://wiki.netbeans.org/FitnessViaPartnership] ,
+that was last modified by NetBeans user Cyhelsky
+on 2013-10-04T12:02:43Z.
+
+
+This document was automatically converted to the AsciiDoc format on 2020-03-14, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/FitnessViaPostMortem.asciidoc b/netbeans.apache.org/src/content/wiki/FitnessViaPostMortem.asciidoc
new file mode 100644
index 0000000..003f514
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/FitnessViaPostMortem.asciidoc
@@ -0,0 +1,168 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+= FitnessViaPostMortem
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: How it works?
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+
+This is a continuation of the
+link:FitnessViaPartnership.asciidoc[FitnessViaPartnership] that enhances the
+original ideas with automatic postmortem identification and notification of
+problems. Done as part of link:Fitness.asciidoc[performance work for 6.8].
+
+* Infrastructure: https://bz.apache.org/netbeans/show_bug.cgi?id=166023[IZ 166023]
+* Bugs reported with *perf-profileme* status board: link:https://bz.apache.org/netbeans/buglist.cgi?bug_file_loc_type=substring&bugidtype=include&chfieldto=Now&cmdtype=doit&emailassigned_to1=1&emailreporter2=1&emailtype1=substring&emailtype2=substring&field0-0-0=noop&keywords_type=anywords&long_desc_type=substring&order=Reuse%20same%20sort%20as%20last%20time&query_format=advanced&short_desc_type=substring&status_whiteboard=perf-profileme&status_whiteboard_type=substring&type0-0-0=noop[list]
+
+
+== How it works?
+
+image:notification_FitnessViaPostMortem.png[]
+
+* Detects that AWT thread is blocked for more than certain time (100ms in dev builds, 10s in final production build)
+* Starts self-sampling profiling
+* As soon as AWT thread is free:
+** stops the profiling
+** if the elapsed time is more than link:http://performance.netbeans.org/responsiveness/whatisresponsiveness.html[appropriate] (3s in dev builds, 20s in final production build), it displays a notification
+** the notification stays on for a minute, then it disappears
+* What are the user's options?
+** ignore the icon (disappears after a minute)
+** submit a bug report via link:FitnessViaPostMortemAutoReport.html[FitnessViaPostMortemAutoReport]
+*¿ explore the content themselves (view data/show profiler data and work in editor as the dialog is modal)
+
+
+[[What_our_users_shall_do]]
+=== What our users shall do?
+
+
+[[Enabling_the_slowness_detector]]
+==== Enabling the slowness detector
+
+The slowness detector is enabled by default in development builds and beta builds. However, it is disabled by default in final releases in NetBeans, and in release candidates. To enable the slowness detector in the FCS and RC builds, it is necessary to enable assertions, i.e. run the IDE with the following switch:
+
+[source,bash,subs="{markup-in-source}"]
+----
+-J-ea
+----
+
+Alternatively, the `-J-ea` parameter can be added to the `netbeans_default_options` property in `etc/netbeans.conf`.
+
+
+[[Not_all_slowness_is_a_problem.]]
+==== Not all slowness is a problem.
+
+Sometimes it may be acceptable. For example if the system wakes up from hibernation, etc. In such case just ignore the report and close it.
+
+
+[[I_don.27t_care_about_slowness]]
+==== I don't care about slowness
+
+In case you are annoyed by the "slowness detector" you may disable it by providing additional properties when launching NetBeans. For example to report only blockages higher than 10s use:
+
+[source,bash,subs="{markup-in-source}"]
+----
+-J-Dorg.netbeans.core.TimeableEventQueue.report=10000
+----
+
+You can also increase the time when the sampling starts:
+
+[source,bash,subs="{markup-in-source}"]
+----
+
+-J-Dorg.netbeans.core.TimeableEventQueue.quantum=1000
+----
+
+Since 6.9 development time there is also _slowness detector_ on code completion. If it takes more than 2s to provide results, it starts self profiling and allows you to complain. You can adjust the time by specifying:
+
+[source,bash,subs="{markup-in-source}"]
+----
+
+-J-Dorg.netbeans.modules.editor.completion.slowness.report=10000
+----
+
+(to be included in 7.0beta2).
+
+
+[[Real_Slowness]]
+==== Real Slowness
+
+If you really noticed the slowness (e.g. blocked mouse, or keyboard input), then you can submit it for evaluation to link:FitnessViaPostMortemAutoReport.html[FitnessViaPostMortemAutoReport] or you can evaluate the snapshot first and then submit it.
+
+To evaluate the snapshot follow these steps: click on the slowness notification icon in bottom right corner, click view data and click show profiler data. Snapshot is open in editor area and you can work with it as above dialog is modal are modal.
+
+Thanks in advance for your help!
+
+
+[[Evaluating_Snapshot]]
+=== Evaluating Snapshot
+
+1. Important things are happening in AWT-Event threads. Explore what is happening there.
+. If the snapshot ends in `Object.wait()` or while waiting on some lock, explore other threads to see who's blocking the evaluation
+
+[[Weird_Behaviour]]
+==== Weird Behaviour
+
+There are some things that can confuse those who evaluate the profiler snapshots taken by the slowness detector. Please be patient, the improvements are in the queue:
+
+* *Sum of time of all threads is wrong* - currently the time of all threads is summed up, which is wrong. We use sampling and we are measuring the real time, not CPU time. The sum for all threads shall be max of all thread times. Confusion among poor developers would be lowered.
+* *Object.wait() interpretation is almost impossible* - Just try to analyse dump from link:http://openide.netbeans.org/issues/show_bug.cgi?id=168536[IZ 168536] and find out why the AWT thread is blocked. Quite hard and some simplification is needed.
+* *Hotspots Tab Unusable* - most developers start understanding of a slowness problem by looking at Hotspots tab of the snapshot. However this is currently unusable as it primarily shows CLI Handler and XAWT-Dispatch threads as the biggest bottleneck (they are waiting for socketAccept or other I/O). This results in large confusion, useless close/reopen bug lifecycle stage, etc.
+* *Inaccurate Snapshots* - the accuracy of the snapshot's data depends on regular execution of the time (e.g. each 10ms a thread dump shall be taken). This may not be satisfied all the time, especially if the system is being awaken from hibernation, etc. This needs to be detected and indicated.
+
+We need help from profiler team to improve the snapshots themselves or simplify life of those who analyse them. Please, help our developers be more productive!
+
+
+[[Plan_to_Address_Weird_Behaviour]]
+==== Plan to Address Weird Behaviour
+
+* image:yes.png[] Have a meeting with profiler guys
+* image:yes.png[] 'Jarda': Write the plan
+* link:NB67PerfPlan/yes.png.html[NB67PerfPlan/yes.png] *native wait* - treat Object.wait and _link:[native.html[[native]_ state equally (e.g. zero execution time)
+* image:yes.png[] *two times* - output two times (execution time, wall clock time) into the .nps file
+* image:yes.png[] *display two times* - make sure the UI represents the two times in some columns
+* image:yes.png[] *no sum for threads* - the sum of all threads execution is incorrect (in sampling or on multicore CPUs), thus hide it
+* image:yes.png[] *JMX* - rewrite the sampler to JMX. This will open the door to possible use in VisualVM as well as provide more info about the real thread execution time
+* image:yes.png[] *overhead* is slightly less than 10% - _Jarda_: measure overhead of sampling (I ran the sieve of erastothenes for first 100000 numbers. Without self profiling 4.1s+-100ms with profiling 4.3ms+-100ms)
+* image:yes.png[] *inaccuracy*: compute average snapshot time and ignore intervals that are far (more than 30ms) from average. Potentially don't report these snapshots at all as a slowdown.
+
+Tentatively:
+
+* *collect wait info*: generate a subnode below Object.wait() or monitor enter(?) with a subtree of other threads activity during the blocked time
+* image:yes.png[] *format*: change the sampling format to be (more or less) GZip of stacktraces. Processing to tree structure would occur later. Done for NetBeans 6.9
+* link:FitnessViaPostMortem.asciidoc[FitnessViaPostMortem]
+
+
+[NOTE]
+====
+
+The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/FitnessViaPostMortem[http://wiki.netbeans.org/FitnessViaPostMortem] , that was last modified by NetBeans user Pjiricka on 2011-04-06T15:24:36Z.
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/FitnessViaTimersCounter.asciidoc b/netbeans.apache.org/src/content/wiki/FitnessViaTimersCounter.asciidoc
new file mode 100644
index 0000000..e54f5a1
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/FitnessViaTimersCounter.asciidoc
@@ -0,0 +1,125 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+
+= FitnessViaTimersCounter
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: Timers/Counters
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+== Timers/Counters
+
+Timers/counters (a.k.a Runtime watches) is a plugin that defined a convention
+based on
+link:http://bits.netbeans.org/dev/javadoc/org-openide-util/org/openide/util/doc-files/logging.html#structured[structured logging]
+for communicating some performance metrics. It depends on <<Probes,probes>> spread over the code of
+interest, but the probes themselves don't depend on the plugin.
+
+
+[[How_to_ensure_acceptable_performance.3F]]
+=== How to ensure acceptable performance?
+
+First, the code needs to have <<Probes,probes>> coded in, so it reports times taken for interesting parts of processing. Then users can see reported times in the runtime watches window as soon as each
+measured action finishes (if they have the plugin installed).
+The probes can also be used from inside a test by registering a special handler for the TIMER logger and using it for collecting the times. Such a test would heavily depend on the configuration and the load of the testing machine, though, so it is not recommended except for properly controlled environment (automated daily tests).
+
+
+[[How_to_fight_against_memory_leaks.3F]]
+=== How to fight against memory leaks?
+
+Again, proper object reference <<Probes,probes>> needs to be in place first so users can potentially see the accumulating objects in the runtime watches window. Then the NbTestCase can be extended to intercept object reference logging messages and collect weak references to the reported objects. At the end of each test, the assertGC can be called for each reference to verify the objects were freed correctly. Of course not every test would want this functionality, so each test would need [...]
+
+
+[[Probes]]
+== Probes
+
+There are two kinds of probes supported currently, but more kinds can be defined, if necessary.
+Each probe reports some information keyed by (usually) two keys that form a hierarchy.
+The primary key is usually a FileObject (but can be any type), while the second is always a String message.
+
+The probe kinds are:
+
+integer value (count, time) :: allows a number (time to perform an operation, number of objects processed during the operation) to be reported with a message and a key. The typical use case would be:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+long time = System.currentTimeMillis();
+int count = parseEverything();
+time = System.currentTimeMillis() - time;
+Logger timer = Logger.getLogger("TIMER");
+timer.log(Level.FINE, "Parsed objects",new Object[] {myFileObject, count});
+timer.log(Level.FINE, "Parsed in [[Ms | ms]]",new Object[] {myFileObject, time});
+----
+
+or some simplification (log only time, only count, less local variables).
+
+object reference :: allows tracking a life cycle of passed object. This is useful if you need to check number of created objects of given kind in given context. The probe would typically end up in the constructor of the object, like:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+SyntaxElement(FileObect fo) {
+ this.fo = fo;
+ Logger.getLogger("TIMER").log(Level.FINE, "SyntaxElements",new Object[] {fo, this});
+}
+----
+
+There is also a simplified way of logging common IDE-wide instaces without the primary key:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+Logger.getLogger("TIMER").log(Level.FINE, "Project:", p);
+----
+
+
+[[Runtime_Watches_Window]]
+=== Runtime Watches Window
+
+Having the probes in your code, you can always inspect their results in the Runtime Watches window. The window can be shown by clicking on the "Run-time Watches" button in the _Memory toolbar_ (next to the memory meter).
+
+You can see registered objects for given keys (usually files) and number of instances. You can invoke _Find References_ to see how the instances are held in memory.
+
+image:RuntimeWatches.png[]
+
+[[Writing_Automated_Tests]]
+=== Writing Automated Tests
+
+It is easy to enhance existing functional tests with checkpoints asserting that all probes of a kind has been released. See link:FitnessMemoryLeaks.asciidoc[FitnessMemoryLeaks].
+
+link:Category:Performance:ToolsAndTests.html[Category:Performance:ToolsAndTests] link:Category:Performance:HowTo.html[Category:Performance:HowTo]
+
+[NOTE]
+====
+
+The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/FitnessViaTimersCounter[http://wiki.netbeans.org/FitnessViaTimersCounter] , that was last modified by NetBeans user Tpavek on 2010-02-18T17:46:48Z.
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/FolderOrdering103187.asciidoc b/netbeans.apache.org/src/content/wiki/FolderOrdering103187.asciidoc
new file mode 100644
index 0000000..f68a18c
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/FolderOrdering103187.asciidoc
@@ -0,0 +1,396 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+
+= FolderOrdering103187
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: Folder Ordering using Numeric Sort
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+Folder ordering using numeric sort.
+
+[[Infrastructure]]
+== Infrastructure
+
+*merged to trunk* (Jun 16 2007)
+link:http://deadlock.netbeans.org/fisheye/changelog/netbeans/?cs=MAIN:jglick:20070616100742[changeset]
+link:http://www.netbeans.org/nonav/issues/show_bug.cgi?id=103187[Issue #103187]
+link:http://deadlock.netbeans.org/hudson/job/trunk/lastSuccessfulBuild/artifact/nbbuild/build/generated/layers.txt[Current SFS with positions]
+
+
+[[Overview]]
+== Overview
+
+
+[[Previous_state]]
+=== Previous state
+
+The Filesystems API specifies no order in folder children (`FileObject.getChildren`).
+But the Datasystems API does assign a meaning to the order of `DataFolder.getChildren`.
+Currently there are four ways a folder may get an order:
+
+1. If the folder attribute `OpenIDE-Folder-Order` is specified, it is used.
+ (Any children not mentioned are put at the end.)
+ The format is `a/b/c` where `a` etc. are file or subfolder names.
+ `DataFolder.setOrder` sets this attribute.
+
+. If the folder attribute `OpenIDE-Folder-SortMode` is specified, it is used.
+ The format is a single character, e.g. `M` for sort by modification time.
+ This method is hardly used any more, although the sort mode attribute is still shown
+ in the property sheet for folder nodes.
+
+. If there are some relative ordering attributes, the folder is topologically sorted.
+ The attribute `a/b`, if set to the value `Boolean.TRUE`, means that
+ `a` should come somewhere before `b` in the folder
+ (not necessarily immediately before).
+
+. Otherwise, the fallback order is alphabetical (same as `OpenIDE-Folder-SortMode=F`).
+
+NOTE: although these methods can apply to any folder, in practice only folders on
+the system filesystem, i.e. defined in XML layers, are explicitly ordered.
+
+
+[[Problems_with_current_state]]
+=== Problems with current state
+
+The third way is the only one suitable for a modular system.
+It has been in use since NetBeans 3.1.
+Unfortunately it suffers from several drawbacks:
+
+1. New developers are confused by ordering attributes.
+ For example, it is common to assume that `a/b` means `a` will immediate precede `b`,
+ which is not the case.
+ It is also common to assume that `a/b=false` is equivalent to `b/a=true`,
+ which is not the case (it has no effect).
+
+. Typing relative ordering attributes in an XML layer is slow and results in bloat
+ since most filenames have to be written three times:
+
+[source,xml]
+----
+<file name="a"/>
+<attr name="a/b" boolvalue="true"/>
+<file name="b"/>
+<attr name="b/c" boolvalue="true"/>
+<file name="c"/>
+<attr name="c/d" boolvalue="true"/>
+<file name="d"/>
+----
+
+. When many unrelated modules contribute to a folder, it is often not clear which modules
+ are more fundamental. (The convention is to have more optional modules declare order
+ relative to more fundamental modules, so the fundamental modules need not know about
+ the optional modules.)
+
+To ensure that the folder order will hold up even when some modules are disabled,
+it is common to overspecify ordering, which can lead to a near-quadratic number of attrs;
+when this is not done, it is common for folders to fall into haphazard order
+as the set of modules changes in unexpected ways.
+
+
+. Attributes often need to be edited to accommodate renames or other changes
+ of unrelated files.
+
+. Contradictory orderings lead to `TopologicalSortException`s, which are unfriendly
+and difficult to debug.
+
+. The module development support has a difficult time writing out ordering attributes
+when the developer uses drag-and-drop to reorder files in an XML layer.
+
+
+[[Solution]]
+=== Solution
+
+To address these problems, the solution is to add a fifth means of ordering a folder.
+Every file in the folder could have a `Number`-valued attribute `position`.
+Files would then be sorted (in increasing order) by position.
+This would also be consistent with `Lookups.metaInfServices`.
+
+For example:
+
+[source,xml,subs="{markup-in-source}"]
+----
+<file name="a"><attr name="position" intvalue="100"/></file>
+<file name="b"><attr name="position" intvalue="200"/></file>
+<file name="c"><attr name="position" intvalue="300"/></file>
+<file name="d"><attr name="position" intvalue="400"/></file>
+----
+
+
+[[Details]]
+== Details
+
+
+[[Ordering_semantics]]
+=== Ordering semantics
+
+Normally positive integers would be used for positions,
+but floats or negative integers could be used for emergencies
+in case an item needed to be inserted between two adjacent integers.
+
+Files with no marked position would be placed at the end (and a brief warning logged).
+Files with the same position would be ordered alphabetically (and a brief warning logged).
+As an exception, you may mark files with the position 0 to indicate that
+their position is irrelevant;
+no warning is logged if several such files exist in the same folder.
+
+Numeric and relative ordering can coexist, for backwards compatibility.
+
+Uses of relative ordering attributes should be logged as warnings
+to assist in migration.
+
+
+[[Setting_order]]
+=== Setting order
+
+`DataFolder.setOrder` should remove any of the old ordering methods in effect
+and set positions on each file in the folder.
+The tricky part is to avoid changing the positions of files which already have positions
+unless necessary to accommodate the new order.
+
+For example, given an initial folder content:
+
+[source]
+----
+a (#100)
+b (#200)
+c (#300)
+d
+----
+
+and asked to set the order to `d a c b`,
+it would be best to change only two attributes, e.g.:
+
+[source]
+----
+d (#0)
+a (#100)
+c (#300)
+b (#400)
+----
+
+or something similar.
+
+I.e. first need to compute a minimal set of transpositions.
+
+TIP: decompose permutation graph into disjoint cycles.
+
+Then use some heuristics to decide
+which of a pair in a transposition to "move",
+and what its new position should be.
+Heuristics could include:
+
+1. Prefer to add a position to a file which lacks one than to change an existing position.
+. Prefer round numbers like 100 to numbers like 123, and prefer integers to floats.
+. Prefer to move a locally modified file to an untouched one.
+ (Can be implemented by looking at position of a `MultiFileObject`'s leader filesystem.)
+
+
+[[Java_APIs]]
+=== Java APIs
+
+Introduce methods to order a folder in `FileUtil` in the Filesystems API,
+and to set a new order.
+This avoids duplicating somewhat subtle code.
+Since callers might be ignoring some files in a folder (e.g. `*.form`)
+the list of files to consider needs to be passed as well.
+
+[source,java,subs="{markup-in-source}"]
+----
+class FileUtil {
+ public static List<FileObject> getOrder(Collection<FileObject> children, boolean logWarnings);
+ /** @postcondition children = getOrder(children, false) */
+ public static void setOrder(List<FileObject> children) throws IOException;
+ public static boolean affectsOrder(FileAttributeEvent event);
+ // ...
+}
+----
+
+(used in: `core/startup`, `core/windows`, `editor/mimelookup/impl`, `openide/loaders`)
+
+
+[[Separators]]
+=== Separators
+
+For menu folders and other places where there is a distinguished null value
+or other separator,
+it is generally permitted to have extra separators.
+(Leading, trailing, or adjacent duplicate separators are ignored.)
+With numeric ordering, a simple convention could help group items into separated blocks.
+
+For example:
+
+[source,xml,subs="{markup-in-source}"]
+----
+
+<file name="sep500"><attr name="position" intvalue="500"/></file>
+<file name="cut"><attr name="position" intvalue="600"/></file>
+<file name="copy"><attr name="position" intvalue="700"/></file>
+<file name="paste"><attr name="position" intvalue="800"/></file>
+<file name="delete"><attr name="position" intvalue="900"/></file>
+<file name="sep1000"><attr name="position" intvalue="1000"/></file>
+<file name="undo"><attr name="position" intvalue="1200"/></file>
+<file name="redo"><attr name="position" intvalue="1300"/></file>
+<file name="sep1500"><attr name="position" intvalue="1500"/></file>
+----
+
+will display as:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+cut
+copy
+paste
+delete
+------
+undo
+redo
+----
+
+but it is easy to add new items at the top, bottom, or middle of any block;
+add new blocks at any position; divide existing blocks; etc.
+
+
+[[SideBar_and_position_attributes]]
+=== SideBar and position attributes
+
+The editor folders under `SideBar` were using a `position`
+attribute for a different purpose.
+These have been converted (compatibly) to use `location` instead.
+
+
+[[Changed_code]]
+== Changed code
+
+Scope is "Big IDE" with all clusters (incl. CND and Profiler).
+
+
+[[Readers_of_relative_ordering_attrs]]
+=== Readers of relative ordering attrs
+
+* `FolderOrder` (`openide/loaders`; also `DataFolder` and `FolderList`)
+ This is the canonical reader of ordering attributes.
+
+* `CompoundFolderChildren` (`editor/mimelookup/impl`; also `FolderChildren`)
+ Does its own reading to order the result of merging together several folders.
+ Víťa agrees it could probably be changed to use `MultiFileSystem` instead,
+ or could use any new sorting API (if it supported parallel folders),
+ or could directly implement sorting by position.
+
+* `OptionUtilities` (`editor`)
+Víťa says it is semi-obsolete, but similar to `CompoundFolderChildren`.
+
+* `ModeParser` (`core/windows`)
+ Prefers to operate at Filesystems API level, for efficiency and predictability.
+ (Using `DataFolder` is slower and introduces asynchronous behavior.)
+
+* `RecognizeInstanceFiles` (`core/startup`)
+ Cannot refer to Datasystems API.
+
+
+[[Writers_of_relative_ordering_attrs]]
+=== Writers of relative ordering attrs
+
+* `LanguagesManager` (`languages/engine`) _(needs tuning)_
+* `MenuFolderNode` and `ToolbarFolderNode` (`core/windows`)
+* `CreatedModifiedFiles` (`apisupport/project`; also `ui.wizard.action.DataModel`)
+* `WritableXMLFileSystem` (`apisupport/project`)
+* `LanguageRegistry` (`scripting/gsf`) _(needs tuning)_
+* `MidpPaletteProvider` (`mobility/designer2/midp`) _(done though untested)_
+
+
+[[Uses_of_relative_ordering_attrs]]
+=== Uses of relative ordering attrs
+
+Fixed in bulk mode using `apisupport/relative2position`.
+
+[[Commit_validation]]
+=== Commit validation
+
+`ValidateLayerConsistencyTest` (in `core`) should verify that:
+
+1. No relative ordering attributes are in use on any folder.
+. Neither `OpenIDE-Folder-Order` nor `OpenIDE-Folder-SortMode` are used.
+. Any `position` attribute has a numeric value.
+. If any file (or subfolder) in a folder has a `position` attribute,
+ then they all do; and all the values are distinct.
+
+_Implemented._
+Run not only in the `trunk` Hudson project (i.e. full IDE),
+but also in `nbms-and-javadoc` (to check experimental modules).
+
+
+[[API_Docs_Updated]]
+=== API Docs Updated
+
+* Modules API.
+* `editor/mimelookup/impl` Javadoc
+* link:DevFaqOrderAttributes.html[DevFaqOrderAttributes]
+* link:NewAndNoteWorthyMilestone10.html[NewAndNoteWorthyMilestone10]
+
+
+[[Misc._impl_still_left_to_do]]
+=== Misc. impl still left to do
+
+* Fix up `LanguagesManager` and `LanguageRegistry`.
+ _(some fixes done already; remainder probably best left to domain developers)_
+
+* Change `FileUtil.setOrder` to be more conservative:
+ avoid changing existing `position` attributes if possible.
+ ''(in progress; cf.
+ link:http://www.netbeans.org/nonav/issues/show_bug.cgi?id=110981[issue #110981])''
+
+* Fix up various ordering attrs which are not quite right.
+ Especially files which claim to be ordered in folders which do not care.
+ Also `Editors/text/*+xml/**` (e.g. Ant context menu) are generally not right.
+ _(generally will be left to whoever handles UI spec conformance bugs)_
+
+* `nbbuild/build.xml#index-layer-paths` ought to order files. _(done)_
+* Need some way of marking a file as not intended to be ordered.
+ E.g. position="0" or position="none".
+ Useful for e.g. hidden subfolders.
+ `getOrder` can put these wherever it likes but should never warn about them.
+ link:http://www.netbeans.org/nonav/issues/show_bug.cgi?id=107550[Issue #107550] _(done)_
+
+* Clean up experimental modules.
+ link:http://deadlock.netbeans.org/hudson/job/nbms-and-javadoc/lastSuccessfulBuild/testReport/org.netbeans.core.projects/ValidateLayerConsistencyTest/testFolderOrdering/[Current errors]
+ _(done)_
+
+
+[NOTE]
+====
+
+The content in this page was kindly donated by Oracle Corp. to the
+Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/FolderOrdering103187[http://wiki.netbeans.org/FolderOrdering103187] ,
+that was last modified by NetBeans user Admin
+on 2009-11-04T22:49:12Z.
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/Group_Priority.png b/netbeans.apache.org/src/content/wiki/Group_Priority.png
new file mode 100644
index 0000000..d53ac38
Binary files /dev/null and b/netbeans.apache.org/src/content/wiki/Group_Priority.png differ
diff --git a/netbeans.apache.org/src/content/wiki/HtmlUIForTemplates.asciidoc b/netbeans.apache.org/src/content/wiki/HtmlUIForTemplates.asciidoc
new file mode 100644
index 0000000..c3b8e12
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/HtmlUIForTemplates.asciidoc
@@ -0,0 +1,269 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+= HtmlUIForTemplates
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: Goals
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+link:Html4Java.html[Html4Java] allows us to easily use HTML based UI in
+NetBeans. This page describes how to build on that ability and enhance our
+template link:API_Design.asciidoc[API]s to allow rich, yet Swing independent UI
+for the template creation wizards.
+
+== Goals
+
+* Play well with 247926 - e.g. templates independent from data loaders
+* Be able to use the wizard values in templating engines - e.g. freemarker
+* Plug into NetBeans wizard API
+* Be embeddable into browser based environment
+
+
+[[Your_Portable_HTML5_Wizard]]
+== Your Portable HTML5 Wizard
+
+To register your HTML based wizard with your template, use link:http://bits.netbeans.org/dev/javadoc/org-netbeans-api-templates/org/netbeans/api/templates/TemplateRegistration.html[@TemplateRegistration] annotation and provide reference to your HTML page:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+public class X {
+ @TemplateRegistration(
+ page = "cz/xelfi/test/x.html",
+ scriptEngine = "freemarker",
+ displayName = "JS Wizard",
+ folder = "Other",
+ content = "x.fmk"
+ )
+ public static String jsWizard() {
+ return "init();";
+ }
+}
+
+----
+
+the return value of the annotated method should of type String and its content should be snippet of JavaScript code to execute inside of your specified HTML page (e.g. *x.html*) to create an instance of link:KnockoutJS.html[KnockoutJS] model to drive the wizard. Here is the sample of the model:
+
+[source,javascript,subs="{markup-in-source}"]
+----
+
+ function init() {
+ var ok = ko.observable(false);
+ var msg = ko.observable('');
+ var current = ko.observable('Init');
+ var data = {
+ 'errorCode': ko.computed(function() {
+ if ('Init' == current()) return 0;
+ if (!ok()) return 1;
+ if (msg()) return 0;
+ return 2;
+ }),
+ 'steps': ko.observableArray([ 'Init', 'Info', 'Summary']),
+ 'current': current,
+ 'ok': ok,
+ 'msg' : msg
+ }
+ return data;
+ }
+
+----
+
+it defines wizard composed of three panels (observable *steps*) and a verification function (registered as *errorCode*) to check if everything is OK. In addition to that it defines proprietary text value *msg* which is going to be filled by the wizard and cannot be empty.
+
+Each page of the wizard is registered as a link:KnockoutJS.html[KnockoutJS] template named according to the name of the specified step. A dummy initial page:
+
+[source,html,subs="{markup-in-source}"]
+----
+
+<script type="text/html" id="Init">
+ <h1>This is Initial Page</h1>
+ <p>
+ JavaScript will ask you few questions about your mood.
+ </p>
+</script>
+
+----
+
+an interactive page with checkbox and an input field:
+
+[source,html,subs="{markup-in-source}"]
+----
+
+<script type="text/html" id="Info">
+ <h1>This is Query Page</h1>
+ <p>
+ Is everything OK?
+ </p>
+ <input type="checkbox" data-bind="checked: ok"/>
+ <p>How do you feel?
+ </p>
+ <input type='text' data-bind="value: msg"/>
+</script>
+
+----
+
+and a simple summary page showing the specified values:
+
+[source,html,subs="{markup-in-source}"]
+----
+
+<script type="text/html" id="Summary">
+ <h1>This is Summary Page</h1>
+ <p>
+ You are feeling <span data-bind="text: msg"></span>!
+ </p>
+</script>
+
+----
+
+The Next/Finish buttons can be controlled by the *errorCode* property. If it is non-zero, there is an error and these buttons are disabled. Also once can use that inside of the HTML page to display user related errors:
+
+[source,html,subs="{markup-in-source}"]
+----
+
+<div data-bind="visible: errorCode() == 1">
+ <span style="color: red">Please check you are OK!</span>
+</div>
+
+<div data-bind="visible: errorCode() == 2">
+ <span style="color: red">Tell us how do you feel!</span>
+</div>
+
+----
+
+The L10N of the wizard is done on the level of HTML pages. The whole page gets translated into different language with appropriate suffix _x_cs.html_ and it is then selected instead of the default one, when user runs in such locale.
+
+When the wizard is successfully finished, all the values specified in the model are transfered to the templating engine, so they can influence the content of created files. Here is a sample _x.fmt_ content which reuses the *msg* value provided by the wizard:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+Hi,
+I am Freemarker.
+I feel ${wizard.msg}.
+
+----
+
+System of this kind is portable between existing NetBeans infrastructure (see branch link:http://hg.netbeans.org/ergonomics/shortlog/62491883f7a0[WizardFor247926] in ergonomics repository) as well as demo of embedding the same wizard into browser (see link:http://xelfi.cz/htmlwizard/[on-line demo]).
+
+
+[[Your_Portable_Html4Java_Wizard]]
+== Your Portable link:Html4Java.html[Html4Java] Wizard
+
+Some people prefer JavaScript, some would rather stick with Java. There is a way to provide the same model for the HTML wizard in Java, just use NetBeans link:Html4Java.html[Html4Java] link:API.html[API]s:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+@Model(className = "Y", properties = {
+ @Property(name = "steps", type = String.class, array = true),
+ @Property(name = "current", type = String.class),
+ @Property(name = "ok", type = boolean.class),
+ @Property(name = "msg", type = String.class)
+})
+public class YCntrl {
+ @ComputedProperty static int errorCode(
+ String current, boolean ok, String msg
+ ) {
+ if ("Init".equals(current)) return 0;
+ if (!ok) return 1;
+ if (msg == null || msg.isEmpty()) return 2;
+ return 0;
+ }
+
+
+ @TemplateRegistration(
+ page = "cz/xelfi/test/x.html",
+ scriptEngine = "freemarker",
+ displayName = "HTML/Java Wizard",
+ folder = "Java",
+ content = "x.fmk"
+ )
+ public static Y jsWizard() {
+ return new Y("Init", false, "",
+ "Init", "Info", "Summary"
+ );
+ }
+}
+
+----
+
+The HTML page remains the same (just remove the JavaScript code) and the application logic is written in Java. Here is a picture showing how the most interactive page looks like when embedded into NetBeans:
+
+image:HtmlWizard.png[]
+
+The picture is identical to the one generated by pure JavaScript driven wizard. Yet one can code and test in a type-safe Java. The result still remains portable as, thanks to link:apidesign:Bck2Brwsr.html[Bck2Brwsr] and other virtual machines like link:apidesign:TeaVM.html[TeaVM], we are capable to run such code in a browser as well.
+
+
+[[Inception_Review]]
+=== Inception Review
+
+The issue is tracked as 248418 and inception review happened on Dec 1, 2014. The following TCRs and TCAs were raised and fixed:
+
+* Avoid knockout templates - uses custom ko binding: link:http://hg.netbeans.org/ergonomics/rev/c5ec0030bd76[http://hg.netbeans.org/ergonomics/rev/c5ec0030bd76]
+* Filter control data - done as link:http://hg.netbeans.org/ergonomics/rev/31f42048137a[http://hg.netbeans.org/ergonomics/rev/31f42048137a]
+* Support for progress bar - this has evolved into supporting validation - done as link:http://hg.netbeans.org/ergonomics/rev/3c0135fb4681[http://hg.netbeans.org/ergonomics/rev/3c0135fb4681]
+* Do not depend on JavaFX - done link:https://hg.netbeans.org/ergonomics/rev/6576fe363d45[https://hg.netbeans.org/ergonomics/rev/6576fe363d45]
+* Prepare Technology Compatibility Kit - done link:http://hg.netbeans.org/ergonomics/rev/c2fce646315b[http://hg.netbeans.org/ergonomics/rev/c2fce646315b]
+
+
+[[Final_Review]]
+=== Final Review
+
+We went through all the previous requirements on Dec 18, 2014 and found their implementation sufficient from an architecture perspective. In addition to that we also got a showcase of apisupport wizard to generate the new wizard: link:http://hg.netbeans.org/ergonomics/rev/c46aa831443d[http://hg.netbeans.org/ergonomics/rev/c46aa831443d]
+
+The whole project seem to be ready for use by NetBeans platform users and was approved for integration, given following is done:
+
+* arch.xml is enhanced with usecases which are currently in the wiki
+* keep in mind the 'global initialization' issue.
+
+Early adopters (like the JBossForge guys) may start testing this technology by end of 2014.
+
+
+[[Global_Initialization_Issue]]
+==== Global Initialization Issue
+
+Currently the JavaScript version of the wizard initializes itself in the HTML page. While this is OK for NetBeans, it may not be acceptable for other (browser with requirejs) environments. Such global initialization might cause name clashes and we need a way to avoid them.
+
+It has been demonstrated that one can avoid it by returning the whole JavaScript initialization code from the method annotated by @TemplateRegistration. So solution exists.
+
+Of course it is not suitable for browser like environment as they may not have the Java method at all. But we will only see once we prototype such browser solutions. Then we will update the "wizard generating the HTML/JS wizard" to layout files more properly so sharing between different environments gets even smoother.
+
+
+[NOTE]
+====
+The content in this page was kindly donated by Oracle Corp. to the
+Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/HtmlUIForTemplates[http://wiki.netbeans.org/HtmlUIForTemplates] ,
+that was last modified by NetBeans user Jtulach
+on 2014-12-22T10:15:41Z.
+
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
+
diff --git a/netbeans.apache.org/src/content/wiki/NbmIdioms.asciidoc b/netbeans.apache.org/src/content/wiki/NbmIdioms.asciidoc
new file mode 100644
index 0000000..3b09a21
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/NbmIdioms.asciidoc
@@ -0,0 +1,403 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+
+= NetBeans APIs in a Nutshell
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:jbake-status: published
+:markup-in-source: verbatim,quotes,macros
+:syntax: true
+:description: NetBeans APIs in a Nutshell
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+
+This overview will quickly familiarize you with how NetBeans modules interact
+with the NetBeans Platform and with each other. It is not intended as a
+comprehensive document—the
+link:http://bits.netbeans.org/dev/javadoc/index.html[NetBeans API List], the
+link:http://netbeans.apache.org/kb/docs/platform.html[NetBeans Platform Learning Trail], and the video series
+"link:https://netbeans.apache.org/tutorials/nbm-10-top-apis.html[Top 10 NetBeans APIs] go into greater detail—but should serve as a guide to
+understanding the basic concepts of NetBeans module development.
+
+The key to understanding the NetBeans Platform is to realize that very often
+the same API or infrastructure does double-duty—playing one role in dealing
+with the user's files on disk, and another role when it comes to configuration
+information and runtime data. For example:
+
+* A link:http://bits.netbeans.org/dev/javadoc/org-openide-filesystems/org/openide/filesystems/FileSystem.html[FileSystem] represents the
+user's files, but the link:https://netbeans.apache.org/tutorials/nbm-glossary.html[System Filesystem] represents the IDE's configuration data.
+* A link:http://bits.netbeans.org/dev/javadoc/org-openide-loaders/org/openide/loaders/DataObject.html[DataObject] represents the
+parsed content of a Java or other file, but DataObjects also are used to instantiate a Java object installed by a module.
+* link:http://bits.netbeans.org/dev/javadoc/org-openide-util-lookup/org/openide/util/Lookup.html#getDefault--[Lookup.getDefault()] is the way you
+access global services and singletons, but you also call link:http://bits.netbeans.org/dev/javadoc/org-openide-nodes/org/openide/nodes/Node.html#getLookup--[Node.getLookup()] to find services specific to an individual file or object.
+
+It is this reuse that has led some to say the NetBeans APIs are confusing, and it is the purpose of this overview to rapidly familiarize you with what these things are and how they are used in both roles.
+
+
+[[FileSystems]]
+== FileSystems
+
+In NetBeans 3.x, adding items to the classpath was accomplished by "mounting" FileSystems - a FileSystem had a root directory and everything under it amounted to a virtual namespace in which files lived.
+
+Since NetBeans 4.0, the "mounting" is gone, and FileSystems are not a concept that users are exposed to in the UI - but the infrastructure behind FileSystems - link:http://bits.netbeans.org/dev/javadoc/org-openide-filesystems/org/openide/filesystems/FileSystem.html[org.openide.filesystems.FileSystem] is alive and well under the hood. In coding NetBeans modules, you will typically interact with instances of link:http://bits.netbeans.org/dev/javadoc/org-openide-filesystems/org/openide/file [...]
+
+
+[[Differences_Between_java.io.File_and_FileObjects]]
+=== Differences Between java.io.File and FileObjects
+
+The main differences between them are as follows:
+
+* You get FileObjects from a FileSystem, rather than create them with a constructor.
+* Typically you don't have FileObjects which represent something that doesn't exist (as you can with new File ("some/place/that/doesnt/exist")).
+* You can listen for changes on FileObjects, including listening on folders for changes that happen anywhere underneath them
+* FileObjects don't necessarily represent actual files on disk
+* FileObjects can have _attributes_ which are essentially key-value pairs that can be associated with a file. An attribute might be a string, or a serialized object (note that use of attributes on user files on disk is discouraged as of NetBeans 4.0, but they are still commonly used in configuration files).
+* The path separator for FileObjects is always /, no conversions with File.separator are needed
+
+
+[[What_FileSystems_Are_Used_For]]
+=== What FileSystems Are Used For
+
+FileSystems are used in two basic but very distinct ways in NetBeans. The first is representing the user's files on disk. To get a FileObject for some path in NetBeans, just call, e.g.
+
+[source,java]
+----
+FileObject text = FileUtil.toFileObject(new File("/.../myFile.txt"));
+----
+
+The second usage is to represent configuration data - this is the "System Filesystem", which is where modules can install their files. Folders in the System Filesystem act as "extension points" - there are some which have predefined meanings (for example, NetBeans' main menu is a tree of folders you will place special "files" into to add menu items); modules are free to create their own folders and do as they wish with the contents.
+
+How does all this work? Well, once you have the concept of a virtualized FileSystem full of FileObjects, it's relatively easy to imagine a FileSystem which took several other FileSystems as arguments, and presented a merged view of the sub-filesystems as if all the data lived in one tree.
+
+Add into this the notion that the "files" in a FileSystem don't actually have to be physical files on disk at all - anything that can be made to walk and talk like a file will do. So you could have an XML "filesystem" where the contents of files lived in an XML document, not a bunch of files on disk.
+
+
+[[XML_Layers]]
+=== XML Layers
+
+That is what the NetBeans Platform does: Each module can define an XML "layer" file, which contains some virtual "files" and folders that are merged into the System Filesystem. In this way modules add their configuration data to the system. And because the System Filesystem is composed from discrete XML fragments from modules, when a module is disabled or unloaded, its XML layer is simply removed. FileObjects for the various folders that had files removed from them fire changes indicatin [...]
+
+In its jar manifest, a module will contain a line such as:
+
+[source,java]
+----
+
+OpenIDE-Module-Layer: org/netbeans/modules/mymodule/layer.xml
+----
+
+This is a pointer to an XML file inside the module jar (meaning that you simply create this file somewhere in your sources so it will be compiled into the jar when your module is built). In its simplest form, that could contain something like:
+
+[source,xml]
+----
+<filesystem>
+ <folder name="myFolder">
+ <file name="myFile.txt" url="resources/aTextFile.txt"/>
+ </folder>
+</filesystem>
+----
+
+The url attribute is important: It says where the contents of myFile.txt lives in the module's jar file. This path is relative to the location of the layer file. So, if the layer file is org/netbeans/modules/mymodule/layer.xml, then in the module jar there should also be a text file org/netbeans/modules/mymodule/resources/aTextFile.txt. When some code requests an InputStream for myFolder/myFile.txt, that text file in the module jar is what will actually be read.
+
+Of course, this particular fragment doesn't do much of anything, but it is useful to illustrate what can be done here. Since myFolder has no predefined purpose to NetBeans, it is up to the module defining that folder to do something with its contents. But one could imagine a module that provided myFolder, let other modules add more files to that folder, and provided one menu item for each file, letting the user view them.
+
+Accessing this file programmatically is quite simple:
+
+[source,java]
+----
+
+FileObject myFile = FileUtil.getConfigFile("myFolder/myFile.txt");
+InputStream in = myFile.getInputStream();
+//...do something with it
+----
+
+
+[[Providing_Java_Objects_through_Module_Layers]]
+==== Providing Java Objects through Module Layers
+
+Just being able to install text files isn't terribly interesting. Where the system of layers gets its power is in the ability to make files act as factories for Java objects. This is made possible using the same infrastructure that recognizes user data on disk, which will be discussed in more detail in the section on Loaders. Effectively, there is a specific file-extension registered in the system, .instance which identifies a file that actually represents a Java object and can create th [...]
+
+[source,xml]
+----
+
+<filesystem>
+ <folder name="Menu">
+ <folder name="File">
+ <file name="org-netbeans-modules-mymodule-MyAction.instance"/>
+ </folder>
+ </folder>
+</filesystem>
+----
+
+The above module layer actually adds a Swing Action (implemented by the class org.netbeans.modules.mymodule.MyAction) into the File menu on the main menu bar in NetBeans. The NetBeans core defines the folder Menu, and provides the infrastructure that listens on these folders and keeps the GUI up-to-date if things are added or removed. Toolbars work in a similar fashion, as do many other things in NetBeans.
+
+
+[[Hiding_Files_in_the_System_Filesystem]]
+==== Hiding Files in the System Filesystem
+
+The System Filesystem also allows one module to remove what another module adds. The semantics are extremely simple - for example, if you wanted to delete the File menu in NetBeans when your module is enabled, simply put the following into your module layer:
+
+[source,xml]
+----
+
+<filesystem>
+ <folder name="Menu">
+ <folder name="File_hidden"/>
+ </folder>
+</filesystem>
+----
+
+
+[[The_System_Filesystem_is_Read-Write]]
+==== The System Filesystem is Read-Write
+
+If it were all just static XML fragments, it wouldn't be possible to actually store configuration changes the user has made - but of course, this is possible. Recall that we have the notion of a filesystem composed of merging multiple other filesystems - and that we know that we have an implementation of FileSystem over actual files on disk, which is how a user's data files are accessed.
+
+The top layer to the system filesystem is the config/ subdirectory of the user's settings directory - typically this lives in the user's home directory under the directory .netbeans. So when a user makes changes (like rearranging menu items), the diff of the changes is written to disk in the settings directory; since this layer lives at the top of the stack, whatever changes are there (such as hiding files, as discussed above), override anything a module has in its layer file.
+
+
+[[DataLoaders_and_DataObjects]]
+== DataLoaders and DataObjects
+
+link:http://bits.netbeans.org/dev/javadoc/org-openide-loaders/org/openide/loaders/DataObject.html[DataObject]link:http://bits.netbeans.org/dev/javadoc/org-openide-loaders/org/openide/loaders/DataObject.html[s] are wrappers for FileObjects. A FileObject simply represents a file-like entity; DataObjects are the level at which the system understands what the contents of a file are. So a module that implements handling for a particular file type provides its own subclass of DataObject and a [...]
+
+The factory for these objects, which a module installs, is called a
+link:http://bits.netbeans.org/dev/javadoc/org-openide-loaders/org/openide/loaders/DataLoader.html[DataLoader].
+
+Unless you are writing support for a language or file-type, typically you will be using, not creating, DataObjects. Getting the DataObject for a file is simple: Just call link:http://bits.netbeans.org/dev/javadoc/org-openide-loaders/org/openide/loaders/DataObject.html#find(org.openide.filesystems.FileObject-[DataObject.find(someFileObject)].
+
+
+[[Using_DataObjects]]
+=== Using DataObjects
+
+DataObjects don't do a lot in and of themselves - that is, it is almost always a mistake to be casting a DataObject as a particular subclass. The way to do most interesting interaction with DataObjects is via the method link:http://bits.netbeans.org/dev/javadoc/org-openide-loaders/org/openide/loaders/DataObject.html#getLookup--[getLookup()]. The pattern, which we will see in more detail in the section on <<Lookup,Lookup>> is:
+
+[source,java]
+----
+
+OpenCookie open = someDataObject.getLookup().lookup(OpenCookie.class);
+open.open();
+----
+
+The above code will actually open a file in the editor. The key here is that, rather than providing programmatic access to a file's content as a bunch of instance methods on itself (which would quickly lead to a tangled mess of inheritance issues), you _ask_ a DataObject for an instance of some known interface that does what you need. This is accomplished by passing a Class object to lookup(), which will return that object if possible, or null if not.
+
+As another example, determining if an opened file has unsaved changes is as simple as:
+
+[source,java]
+----
+
+boolean needsSaving = someDataObject.getLookup().lookup(SaveCookie.class) != null;
+----
+
+Modules can provide their own public interfaces, and make instances of those objects available via lookup. So, for example, a DataObject for an XML file might make a DOM tree or some other structural representation of the file available via lookup for other modules to use to manipulate the file's contents. Some common interfaces modules will typically use via lookup can be found in the package link:http://bits.netbeans.org/dev/javadoc/org-openide-nodes/org/openide/cookies/package-summary [...]
+
+Note that the term "cookie" in this context has nothing to do with the web browser concept of cookies.
+
+
+[[Putting_it_Together:_Why_.instance_Files_Work]]
+=== Putting it Together: Why .instance Files Work
+
+To illustrate the power of loaders and DataObjects, recall that loaders are registered against a file type. And recall that modules can install actual Java objects via .instance files. What's going on here?
+
+What is actually happening is that the very same infrastructure (DataLoaders) that lets NetBeans recognize a user's .java file on disk and create an appropriate DataObject is what recognizes .instance files - after all, the System Filesystem is a filesystem too. There is simply a DataLoader registered in the system that claims all files with the .instance extension.
+
+Under the hood, what's really happening is that the DataObject for a .instance file provides an link:http://bits.netbeans.org/dev/javadoc/org-openide-nodes/org/openide/cookies/InstanceCookie.html[InstanceCookie]. So to get the actual object in question manually, you would do something like this:
+
+[source,java]
+----
+
+FileObject file = FileUtil.getConfigFile("someFolder/com-foo-mymodule-MyClass.instance");
+DataObject dob = DataObject.find(file);
+InstanceCookie cookie = dob.getLookup().lookup(InstanceCookie.class);
+MyClass theInstance = (MyClass) cookie.instanceCreate();
+----
+
+or more simply:
+
+[source,java]
+----
+
+MyClass theInstance = FileUtil.getConfigObject("someFolder/com-foo-mymodule-MyClass.instance");
+----
+
+
+[[Nodes:_The_Presentation_Layer]]
+== Nodes: The Presentation Layer
+
+You've probably noticed that there are quite a few tree components in NetBeans - the Files and Projects tabs, and others. The link:http://bits.netbeans.org/dev/javadoc/org-openide-nodes/org/openide/nodes/doc-files/api.html[Nodes API] is what provides the contents to those trees. Think of DataObjects as being the data model; a Node is where interacting with the user comes in.
+
+A link:http://bits.netbeans.org/dev/javadoc/org-openide-nodes/org/openide/nodes/Node.html[Node] provides human-visible things like an icon and a (possibly localized) display name to DataObjects. And a Node provides a list of link:http://bits.netbeans.org/dev/javadoc/org-openide-awt/org/openide/awt/Actions.html[Actions] that can appear in a popup menu for that node.
+
+Nodes define _context_ for NetBeans - at any given moment, there is usually one or more _activated nodes_ which determine what menu and toolbar actions are enabled - they are the clue to the rest of the system as to what the user is doing. Each UI component (such as the Files tab or the Editor) provides an array of Nodes which are activated - selected. In a tree component, it is rather obvious how this works; but even when editing in the editor, the activated node triggers what actions a [...]
+
+So, to get the Node corresponding to a DataObject, simply call someDataObject.link:http://bits.netbeans.org/dev/javadoc/org-openide-loaders/org/openide/loaders/DataObject.html#getNodeDelegate()[getNodeDelegate()].
+
+
+[[Nodes.2C_DataObjects_and_lookup_Patterns]]
+=== Nodes, DataObjects and lookup Patterns
+
+Nodes use the same pattern as DataObject - they have a getLookup() method that can be used as described above. Nodes that represent DataObjects will typically delegate to their DataObject's getLookup() method.
+
+Note that all Nodes do not represent DataObjects - the Nodes API is useful in and of itself for creating tree like hierarchies.
+
+There are a number of UI components that can represent a tree of nodes as trees, combo boxes, lists, etc. - so typically when one needs to display a UI with a list or tree in it, the natural choice is to use the Nodes API, and simply create the appropriate component and set the root node appropriately.
+
+A key thing to remember is that Nodes are intended as a presentation layer for an underlying data model (which might be files on disk, or whatever you want). If you find you're putting a lot of logic into your Node subclass, consider that your model is what needs enhancing - Nodes should be lightweight and simple, and the model should do the heavy lifting.
+
+
+[[Lookup]]
+== Lookup
+
+link:http://bits.netbeans.org/dev/javadoc/org-openide-util-lookup/org/openide/util/Lookup.html[org.openide.util.Lookup] is NetBeans' form of the "service locator" and "adapter" patterns. As with DataObjects and FileObjects, it has two common usages:
+
+* _Local lookup_ - asking an object for an instance of some interface, as we saw above with Node.getLookup().lookup(SomeClass.class)
+* _Global lookup_ - services - often singleton instances of some class - can be registered into the _default lookup_.
+
+
+[[The_Default_Lookup]]
+=== The Default Lookup
+
+The default lookup is an instance of Lookup returned by calling Lookup.getDefault(). The NetBeans APIs define a number of abstract service classes which allow you to get an instance of some object that is of general use - for example, link:http://bits.netbeans.org/dev/javadoc/org-openide-dialogs/org/openide/DialogDisplayer.html[org.openide.DialogDisplayer], which displays dialogs to the user. These are typically things that there only needs to be one of in the system, so they are effecti [...]
+
+[source,java]
+----
+
+DialogDisplayer d = Lookup.getDefault().lookup(DialogDisplayer.class);
+d.notify(...);
+----
+
+In practice this code is a little clunky to ask people to write all the time, so most such abstract classes will have their own method getDefault() implemented as:
+
+[source,java]
+----
+
+public abstract class MyService {
+ public static MyService getDefault() {
+ MyService result = Lookup.getDefault().lookup(MyService.class);
+ if (result == null) {
+ result = new TrivialImplementationOfMyService();
+ }
+ return result;
+ }
+ public abstract void doSomething(...);
+}
+----
+
+Modules can register their own objects into the default lookup using the @ServiceProvider annotation.
+
+While we won't go into this in detail here, it is also possible to register multiple instances of an interface into the default lookup, retrieve all of them and even listen for changes on the result of that query.
+
+A very thorough discussion of Lookup can be found link:http://openide.netbeans.org/lookup/[here].
+
+
+[[Summary]]
+=== Summary
+
+The salient points to remember are:
+
+* FileObjects wrap files (and sometimes other things)
+* DataObjects wrap FileObjects and understand what's in a file
+* You typically don't call methods on a DataObject, you ask it for objects via getLookup().lookup(...)
+* Configuration information is just another filesystem you can get DataObjects out of
+* Nodes wrap DataObjects and provide human-displayable information - actions, icons, names
+* Nodes are a presentation layer, not the place to put lots of logic
+* Lookup is how you get globally registered services
+* Lookup is also how you ask individual objects (Nodes, DataObjects, Projects) for the objects that do real work
+
+
+[[Interconverting_between_Files.2C_DataObjects.2C_FileObjects_and_Nodes]]
+== Interconverting between Files, DataObjects, FileObjects and Nodes
+
+Very often you may be integrating an external tool that wants to be passed instances of java.io.File; also there are many cases where you need to interconvert between the various types NetBeans offers which in some way or other represent files.
+
+Here are the typical ways to interconvert between all of the above:
+
+[source,java]
+----
+//Find a file on disk
+FileObject f = FileUtil.toFileObject(new File("/some/folder/someFile.txt"));
+//Turn a FileObject into a File (may fail for virtual filesystems)
+File f = FileUtil.toFile(someFileObject);
+//Get the DataObject for a FileObject
+DataObject obj = DataObject.find(someFileObject);
+//Get the FileObject a DataObject represents
+FileObject file = someDataObject.getPrimaryFile();
+//Get the Node that represents a FileObject
+Node n = someDataObject.getNodeDelegate();
+//Get the DataObject a Node represents (if any)
+DataObject obj = someNode.getLookup().lookup(DataObject.class);
+----
+
+
+[[Other_Things_Worth_Mentioning...]]
+== Other Things Worth Mentioning...
+
+Below we go through two other critical pieces of NetBeans APIs which complete
+the basic picture of things modules typically interact with; they don't have
+the type of dual-use issues that the previous topics do, but are included for
+completeness.
+
+
+[[Explorer_Views]]
+=== Explorer Views
+
+Nodes provide a hierarchy of objects; the Explorer API provides Swing UI
+components that display a Node and its children. There are a large variety of
+Explorer view classes which can variously represent a hierarchy of Nodes as a
+JList, a JMenu, a JComboBox, a JTree, a JTable and more. Typically when you
+want to display some hierarchical data structure in NetBeans, you locate or
+implement the appropriate Node, create an appropriate Explorer component for
+it, and set the Explorer view's root node to be the node you want to display.
+
+In older versions of NetBeans, the place where the Files and Projects tabs live
+was a separate window with the title "Explorer" - you will see the phrase "open
+in the Explorer" in older documentation.
+
+
+[[The_Window_System]]
+=== The Window System
+
+The API of the Window System is found in link:http://bits.netbeans.org/dev/javadoc/org-openide-windows/org/openide/windows/package-summary.html[org.openide.windows]. A basic overview is that in NetBeans, you don't deal with JFrames or JDialogs - rather, you supply components which are displayed, and NetBeans window management system decides where and how they appear in terms of top-level frames. The main thing to know is that all components in NetBeans are subclasses or usages of link:ht [...]
+
+TopComponents can be instantiated and opened on the fly, but typically a module installs its UI components via several XML files inside its JAR file and pointers to those files in the module's XML layer file.
+
+
+[[When_Youre_Wondering_Where_Something_is_Implemented]]
+== When You're Wondering Where Something is Implemented
+
+Sometimes you just want to go read the code - but it's a jungle of jars out there. Here are some of the things people often want to track down - the locations are the actual directories in a checkout of NetBeans sources:
+
+* *Where are the standard menus defined?* - core.ui
+* *Where is dialog and windowing handled?* - core.windows
+* *Where is the tab control NetBeans uses for tabs?* - o.n.swing.tabcontrol
+* *What sets the fonts for NetBeans?* - o.n.swing.plaf
+
+[NOTE]
+====
+The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/NbmIdioms[http://wiki.netbeans.org/NbmIdioms] , that was last modified by NetBeans user Yirco on 2012-08-25T13:31Z.
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
+
diff --git a/netbeans.apache.org/src/content/wiki/ParsingAPI.asciidoc b/netbeans.apache.org/src/content/wiki/ParsingAPI.asciidoc
new file mode 100644
index 0000000..ab944b9
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/ParsingAPI.asciidoc
@@ -0,0 +1,197 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+= ParsingAPI
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: Quick Links to Turorials and Docs
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+== Quick Links to Turorials and Docs
+
+* http://netbeans.apache.org/tutorials/nbm-javacc-lexer.html
+* http://netbeans.apache.org/tutorials/nbm-javacc-parser.html
+* link:http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-parsing-api/overview-summary.html[Official Doc (JavaDoc)]
+
+
+[[Motivation]]
+== Motivation
+
+NetBeans IDE is no longer just Java IDE. We support many various languages:
+Java, Ruby, PHP, JSP, Javascript and so on. Each language support module
+implements its own parsing framework. We have Retouche for Java, GSF for Ruby,
+Schliemann. Now is the right time to consiladate those framworks in order to
+avoid code duplication, improve performance, solve threading issues,
+consolidate features and allow language embedding.
+
+
+[[Description]]
+== Description
+
+We want to create Parsing API to:
+
+* Unify registration of parsers
+* Allow language embedding
+* Allow file indexing
+* Unify threading, starting/canceling parser tasks
+* Avoid code duplication
+* Simplify implementation of language supports
+
+
+[[Current_Status]]
+== Current Status
+
+|===
+|Plugin |Go/No Go |Status
+
+|CSS |Done.
+
+|Groovy |Done, bugfixing.
+
+|GSP |Done, bugfixing.
+
+|HTML |Done, bugfixing.
+
+|Javascript |Done, bugfixing.
+
+|JSP |Done, bugfixing.
+
+|PHP |Done, bugfixing.
+
+|Python |In progress.
+
+|RHTML |Done, bugfixing.
+
+|Ruby |Done, bugfixing.
+
+|YAML |Done, bugfixing.
+
+|JavaFX |Done
+
+|Ada |Done, bugfixing. (contrib)
+
+|EJS |Not planned for 6.7 (contrib)
+
+|Erlang |Rewrite done (?) -- link:http://blogtrader.net/[Status]
+
+|Fortress |Not planned for 6.7 (contrib)
+
+|Scala |Done, bugfixing. (contrib)
+
+|Tcl/Tk |Not planned for 6.7 (contrib)
+|===
+
+
+[[Impacts]]
+== Impacts
+
+
+[[Architecture]]
+=== Architecture
+
+
+[[API]]
+=== API
+
+We have experience with Retouche, GSF and Schliemann and we want to make an API, which will rise from our experience with those frameworks. The API is not intend to be revolutionary. It is evolutionary development.
+
+The API will have several parts:
+
+1. Parsing
+* Defines registration of parsers
+* Defines threading
+* Concept of Virtual Source (support for language embedding)
+* No support for phases
+* No ordering of parsers
+. Indexing
+* Provides scanning infrastructure
+* Allows registration of Index providers
+* RepositoryUpdater - listening on file and document changes
+. "Generic ClassPath"
+* Provides something like ClassPath to specify source roots (folders, archives)
+. UserAction and Modification tasks
+* Change represented by ModificationResult (in fact textual diff)
+* Need source position translators for embedded languages
+
+
+[[Documentation]]
+=== Documentation
+
+API must be well documented. Developer documentation is a must.
+
+[[Testing]]
+=== Testing
+
+* Unit testing.
+* Functional testing through language support modules.
+
+
+[[Performance]]
+=== Performance
+
+* Well defined threading and starting/canceling parser tasks could improve performance of code completion and features in various Editors
+* Startup scanning will be slower because of scanning and indexing not only Java, but possibly all files
+
+
+[[Tasks]]
+== Tasks
+
+We have been tracking all tasks related to Parsing API in IssueZilla under *Editor / Parsing & Indexing* category. Please use the following
+link:http://editor.netbeans.org/issues/buglist.cgi?component=editor;subcomponent=Parsing%20%26%20Indexing;issue_status=NEW;issue_status=STARTED;issue_status=REOPENED;&order=issues.priority%2C%20issues.issue_id[query] to see all unresolved issues sorted by their priority.
+
+
+[[Bugs]]
+== Bugs
+
+* link:http://www.netbeans.org/issues/buglist.cgi?issue_status=NEW&issue_status=STARTED&issue_status=REOPENED&email1=&emailtype1=exact&emailassigned_to1=1&email2=&emailtype2=exact&emailreporter2=1&issueidtype=include&issue_id=&changedin=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&short_desc=&short_desc_type=substring&long_desc=&long_desc_type=substring&issue_file_loc=&issue_file_loc_type=substring&status_whiteboard=parsingapi&status_whiteboard_type=substring&keywords=&keywords_type= [...]
+* link:http://www.netbeans.org/issues/buglist.cgi?issue_status=NEW&issue_status=STARTED&issue_status=REOPENED&status_whiteboard=works_in_parsingapi&status_whiteboard_type=substring[List of (trunk) bugs fixed by the parsing API]
+
+
+[[Additional_information]]
+== Additional information
+
+* Send comments to link:mailto:dev@netbeans.apache.org[dev@netbeans.apache.org]
+* link:http://wiki.netbeans.org/wiki/view/EditorSupportChangesProposal[Editor Support Changes Proposal]
+* link:ParsingAPIRequirements.html[Parsing API - Use cases, Requirements]
+* link:http://www.netbeans.org/issues/show_bug.cgi?id=137084[GSF Inception Review]
+* link:http://www.netbeans.org/issues/show_bug.cgi?id=127357[Parsing API Inception Review]
+* link:ParsingAPITCReview.html[Parsing API Technical Council Review ]
+* link:GsfToParsingAndIndexingApiMigration.html[Migrating GSF-based language plugins to Parsing & Indexing API]
+
+
+[NOTE]
+====
+
+The content in this page was kindly donated by Oracle Corp. to the
+Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/ParsingAPI[http://wiki.netbeans.org/ParsingAPI] ,
+that was last modified by NetBeans user Mr lou d
+on 2015-01-08T09:23:40Z.
+
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/Profileme_FitnessViaPartnership.png b/netbeans.apache.org/src/content/wiki/Profileme_FitnessViaPartnership.png
new file mode 100644
index 0000000..38f10e9
Binary files /dev/null and b/netbeans.apache.org/src/content/wiki/Profileme_FitnessViaPartnership.png differ
diff --git a/netbeans.apache.org/src/content/wiki/RunConfigurations49636.asciidoc b/netbeans.apache.org/src/content/wiki/RunConfigurations49636.asciidoc
new file mode 100644
index 0000000..39bf616
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/RunConfigurations49636.asciidoc
@@ -0,0 +1,156 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+
+= RunConfigurations49636
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: Run Configurations for Java SE Projects
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+== Run Configurations for Java SE Projects
+
+Links:
+
+* link:http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-projectapi/org/netbeans/spi/project/doc-files/configurations.html[Technical specification]
+* link:http://www.netbeans.org/nonav/issues/show_bug.cgi?id=49636[Tracking issue for Java SE projects]
+* link:http://www.netbeans.org/nonav/issues/show_bug.cgi?id=49652[Tracking issue for API]
+* link:NewAndNoteWorthyMilestone3#RunConfigurationsForJavaSEProjects.html[Release note]
+
+
+[[Demo_Script]]
+== Demo Script
+
+Prerequisites:
+
+1. NetBeans 6.0 (tested against 20070419 ~ M9)
+. JDK 6.0u1
+. Any supported OS (tested on Ubuntu)
+
+Preparation:
+
+1. Create a Java application.
+. Add to the main method:
+
+[source,java]
+----
+ System.out.println("First main class.");
+----
+
+. Add a new Java main class. Add to its main method:
+
+[source,java]
+----
+System.out.println("Second main class.");
+----
+
+. Click *Run* (F6). You should see
+
+[source,bash]
+----
+run:
+First main class.
+BUILD SUCCESSFUL
+----
+
+Demo steps:
+
+1. From the *<default>* combo in the toolbar, select *Customize...*.
+. Click *New...* (configuration).
+. Enter name `second` and click *OK*.
+. Click *Browse...* (for main class).
+. Pick the second class and click *Select Main Class*.
+. Click *OK* to close the *Properties* dialog.
+. Click *Run*; you should see
+
+[source,bash]
+----
+run:
+Second main class.
+BUILD SUCCESSFUL
+----
+
+1. Choose *<default>* again in the combo and click *Run*; you should see the first main class again.
+. Right-click the project and choose *Properties*.
+. Under *Run*, switch to *second* configuration.
+. Add `-showversion` to *VM Options*. Note that the field's label becomes boldfaced.
+. Click *OK* and *Run*; you should see
+
+[source]
+----
+run:
+java version "1.6.0_01"
+JavaTM SE Runtime Environment (build 1.6.0_01-b06)
+Java HotSpotTM Server VM (build 1.6.0_01-b06, mixed mode)
+
+Second main class.
+BUILD SUCCESSFUL
+----
+
+
+[[Optional_material]]
+== Optional material
+
+Question: Can I control other things besides *Run* options?
+
+Answer: You can, though for at least for 6.0 this is not supported through the GUI. For example, go to the *Files* tab and open `nbproject/configs/second.properties`. Add:
+
+[source,bash]
+----
+build.compiler=extJavac
+javac.compilerargs=-J-showversion
+----
+
+With the configuration set to *second*, press *Clean and Build Main Project* (S-F11). You should see
+
+[source,bash]
+----
+Compiling 2 source files to /tmp/JavaApplication1/build/classes
+java version "1.6.0_01"
+Java(TM) SE Runtime Environment (build 1.6.0_01-b06)
+Java HotSpot(TM) Client VM (build 1.6.0_01-b06, mixed mode, sharing)
+
+compile:
+----
+
+Generally, anything normally set in `project.properties` can be overridden on a
+per-configuration basis. The *Properties* dialog outside the *Run* panel will
+only show the contents of `project.properties`, however.
+
+
+[NOTE]
+====
+
+The content in this page was kindly donated by Oracle Corp. to the
+Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/RunConfigurations49636[http://wiki.netbeans.org/RunConfigurations49636] ,
+that was last modified by NetBeans user Jglick
+on 2010-02-19T17:02:01Z.
+
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/RuntimeWatches.png b/netbeans.apache.org/src/content/wiki/RuntimeWatches.png
new file mode 100644
index 0000000..5c01dde
Binary files /dev/null and b/netbeans.apache.org/src/content/wiki/RuntimeWatches.png differ
diff --git a/netbeans.apache.org/src/content/wiki/SigTest.asciidoc b/netbeans.apache.org/src/content/wiki/SigTest.asciidoc
new file mode 100644
index 0000000..c047725
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/SigTest.asciidoc
@@ -0,0 +1,235 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+= SigTest
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:jbake-status: published
+:syntax: true
+:description: New Home
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+`SigTest` is the tool behind NetBeans link:SignatureTest.asciidoc[signature
+testing] infrastructure. It checks for incompatibilities between different
+versions of the same API.
+
+[[New_Home]]
+== New Home
+
+Please continue at link:https://github.com/jtulach/netbeans-apitest#readme[https://github.com/jtulach/netbeans-apitest#readme]
+that is the new home since NetBeans migrated to Apache.
+
+
+[[Old_Content_Follows]]
+== Old Content Follows
+
+NetBeans uses the link:APITest.asciidoc[APITest] tool as an Ant task to check
+for binary backward compatibility and mutual signature compatibility. There is
+however also a version released as a
+link:https://search.maven.org/search?q=a:sigtest-maven-plugin[sigtest-maven-plugin]
+ready for use in your own project. The
+link:https://github.com/jtulach/netbeans-apitest[sources] were converted to
+GitHub repository and are available under GPL version 2.
+
+[[Use_in_Maven]]
+== Use in Maven
+
+The sigtest Maven Plugin is available on link:https://search.maven.org/search?q=a:sigtest-maven-plugin[sigtest-maven-plugin at Maven Central]
+thus it is easily embeddable it into your own project.
+
+[[Generate_the_Signature_File]]
+=== Generate the Signature File
+
+The first thing to do is to generate snapshot of API of your library - e.g. the
+signature file.
+
+Just add following into your own `pom.xml` file:
+
+[source,xml]
+----
+<plugin>
+ <groupId>org.netbeans.tools</groupId>
+ <artifactId>sigtest-maven-plugin</artifactId>
+ <version>1.2</version>
+ <executions>
+ <execution>
+ <goals>
+ <goal>generate</goal>
+ </goals>
+ </execution>
+ </executions>
+ <configuration>
+ <packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
+ </configuration>
+</plugin>
+----
+
+with just this change the API of your classes in the listed packages is going
+to be recorded into a `.sigtest` file and included as an artefact of your
+project when you invoke `mvn install`.
+
+For example libraries of Html4Java NetBeans API
+link:https://repo1.maven.org/maven2/org/netbeans/html/net.java.html.json/1.3/[have the sigtest file]
+attached in Maven central with link:http://hg.netbeans.org/html4j/rev/833829b33779[this changeset].
+
+
+[[Check_Against_Signature_File_in_a_Repository]]
+=== Check Against Signature File in a Repository
+
+Once the `sigfile` is part of a Maven repository, you want to check your new
+APIs against that API _snapshot_ to make sure you are not making incompatible
+changes. Try the following:
+
+[source,xml]
+----
+
+<plugin>
+ <groupId>org.netbeans.tools</groupId>
+ <artifactId>sigtest-maven-plugin</artifactId>
+ <version>1.2</version>
+ <executions>
+ <execution>
+ <goals>
+ <goal>check</goal>
+ </goals>
+ </execution>
+ </executions>
+ <configuration>
+ <packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
+ <releaseVersion>1.3</releaseVersion>
+ </configuration>
+</plugin>
+
+----
+
+The difference is the goal - e.g. *check* and also the need to specify
+*releaseVersion* - that is the identification of the previously released
+version of your library that you want to check compatibility against.
+
+And that is all! To verify the setup is correct, try to remove a method or do
+some other incompatible change.
+
+When I tried and executed `mvn install` I got a build failure:
+
+[source]
+----
+SignatureTest report
+Base version: 1.3
+Tested version: 2.0-SNAPSHOT
+Check mode: bin [throws removed]
+Constant checking: on
+
+Class net.java.html.json.Models
+ "E1.2 - API type removed" : method public final static void net.java.html.json.Models.applyBindings(java.lang.Object,java.lang.String)
+
+
+
+target/surefire-reports/sigtest/TEST-json-2.0-SNAPSHOT.xml: 1 failures in /.m2/repository/json/1.3/json-1.3.sigfile
+ ------------------------------------------------------------------------
+BUILD FAILURE
+----
+
+This is the way Html4Java enabled signature testing: see link:http://hg.netbeans.org/html4j/rev/031e46d048d8[changeset] mixing both goals together.
+
+
+[[Fail_on_Error]]
+==== Fail on Error
+
+You may want to control whether a failure in signature test should be fatal or not. Do it with:
+
+[source,xml]
+----
+
+ <configuration>
+ <failOnError>false</failOnError>
+
+ <packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
+ <releaseVersion>1.3</releaseVersion>
+ </configuration>
+
+----
+
+With this configuration the test will be performed and output printed, but the build will go on. This may be useful when one needs to do an incompatible change and wants to disable the check until next version is published.
+
+
+[[Prevent_Any_Change]]
+==== Prevent Any Change
+
+By default the plugin verifies there are no *incompatible* changes. However compatible changes are allowed. Sometimes it is useful to prevent any changes altogether (when creating a bugfix release, for example), then try:
+
+[source,xml]
+----
+
+ <configuration>
+ <action>strictcheck</action>
+
+ <packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
+ <releaseVersion>1.3</releaseVersion>
+ </configuration>
+
+----
+
+with the *action* option set to _strictcheck_ the plugin will detect any API change and fail even if it is compatible.
+
+
+[[Whos_Using_SigTest]]
+== Who's Using SigTest
+
+NetBeans SigTest is used by:
+
+* NetBeans uses it as an Ant task
+* Html4Java APIs use it as Maven plugin
+* Oracle Labs link:https://github.com/graalvm/truffle[Truffle project] integrates it into link:http://wiki.apidesign.org/wiki/TruffleSigTest[their own build tool].
+* link:http://dukescript.com[DukeScript] project for its link:https://github.com/dukescript/DefinitelyTyped[Definitely Typed Java API] for all JavaScript libraries
+
+
+[[Develop]]
+== Develop
+
+Binary Builds are available from our link:http://deadlock.netbeans.org/hudson/job/apitest/[hudson builder]. Get the sources with
+
+[source,bash]
+----
+hg clone http://hg.netbeans.org/apitest/
+cd apitest
+ant jar test
+# open in NetBeans
+----
+
+Contact the developer via email jtulach (at) netbeans.org - and don't forget to
+read link:http://wiki.apidesign.org/wiki/TheAPIBook[Practical API Design] book.
+
+
+[NOTE]
+====
+
+The content in this page was kindly donated by Oracle Corp. to the
+Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/SigTest[http://wiki.netbeans.org/SigTest] ,
+that was last modified by NetBeans user Jtulach
+on 2019-04-10T05:59:08Z.
+
+
+This document was automatically converted to the AsciiDoc format on 2020-03-15, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/SignatureTest.asciidoc b/netbeans.apache.org/src/content/wiki/SignatureTest.asciidoc
new file mode 100644
index 0000000..d051673
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/SignatureTest.asciidoc
@@ -0,0 +1,230 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+= SignatureTest
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: Use from Maven
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+Signature tests verify that public and protected members of non-private classes
+in each module do not change or remain compatible with previous version. These
+tests are part of the build or the
+link:http://deadlock.netbeans.org/hudson/[continuous build process]. The
+testing infrastructure is currently based on link:APITest.asciidoc[APITest], an
+extension and temporary fork of link:http://sigtest.java.net/[sigtest tool]
+which is used as part of the link:http://www.jcp.org/[JCP] test compatibility
+kits to verify that the API exposed by a JSR implementation does not diverge
+from the reference implementation.
+
+[[Use_from_Maven]]
+== Use from Maven
+
+See link:SigTest.asciidoc[SigTest] for the details.
+
+[[Consistency_Check]]
+== Consistency Check
+
+*Turned on Nov 7, 2012*:
+
+For a while the link:VersioningPolicy.asciidoc[VersioningPolicy] prescribes how
+to properly version modules and their API changes. However the policy has for a
+long time only been applied to modules with stable API. From time to time this
+leads to _no such method or class_ errors like {{iz|186233 which need to be
+evaluated by _platform/module system_ component owner.
+
+Moreover the introduction of incremental binary build
+link:AutoUpdateTask.asciidoc[AutoUpdateTask] requires more proper attitude to
+versioning. Only then one can be sure that incremental binary build really
+links properly.
+
+For the above reasons ita consistency check that verifies minimal versioning
+consistency has been introduced. The
+link:HgParallelProjectIntegration.html[HgParallelProjectIntegration] runs:
+
+* Check on all modules exposing non-private packages
+* Compares the spec version.
+** If the new spec is the same as previous, the check fails if there is some API change (method or class)
+** If the new spec is higher, the check will pass regardless of any API changes.
+
+The check is integral part of push-* jobs and if it detects a failure, the push job fails. *To recover* you are supposed to increment spec version of your module whenever you change its API. Increment spec versions of modules that depend on your API change as well (not enforced right now). Run following command to simulate the check locally:
+
+[source,bash,subs="{markup-in-source}"]
+----
+# first of all make sure your system is built OK
+# Then either:
+# generate appropriate JUnit testing report for all modules:
+$ ant check-sigtests-version
+#
+# or run the 'version' check for a single module
+$ ant -f your.module/build.xml check-sigtest -Dsigtest.check.type=versioncheck
+
+----
+
+
+[[Continuous_Check_for_Changes]]
+== Continuous Check for Changes
+
+The link:http://deadlock.netbeans.org/hudson/[continuous build process] runs a sigtest build that compares APIs in a new build with APIs of the one of the previous build. Whenever there is a change (either compatible or incompatible) a mail is sent:
+
+* if the module has public packages - to the link:mailto:api-changes@netbeans.org[api-changes@netbeans.org] mailing list
+* if the module has friends in other clusters - to the link:mailto:api-changes@netbeans.org[api-changes@netbeans.org] mailing list
+* if the module has friends only in the same cluster - to appropriate *cvs@<module>.netbeans.org* mailing list
+* if the module has neither friends, neither public packages - it is skipped from the check
+
+Appropriate owners of each module and tech leads of each area are expected to review the change and prevent or revert unintentional changes.
+
+The link:http://deadlock.netbeans.org/hudson/job/nbms-and-javadoc/lastSuccessfulBuild/artifact/nbbuild/build/sigtest/snapshot/[signature golden files] are generated by
+
+[source,bash,subs="{markup-in-source}"]
+----
+
+$ ant -f nbbuild/build.xml gen-sigtests
+----
+
+and compared by
+
+[source,bash,subs="{markup-in-source}"]
+----
+
+$ ant -f nbbuild/build.xml gen-sigtests
+----
+
+A module can configure sigtest behavior by modifying its *project.properties*:
+
+[source,bash,subs="{markup-in-source}"]
+----
+
+# redefine the email where reports are sent
+sigtest.mail=your.name@your.org
+# don't fail if the generation of the report fails
+sigtest.gen.fail.on.error=false
+
+----
+
+
+[[At_the_time_of_release]]
+== At the time of release
+
+When doing a release it is important to record the actual signatures of _stable_ modules (and to some extend also _under development_ ones), so we know what to keep link:apidesign::BackwardCompatibility.html[backward compatibility] with. To generate these signatures we used to do following, but since link:https://github.com/apache/incubator-netbeans/pull/1064[Apache NetBeans is in Git], it is better to follow the link:https://github.com/apache/incubator-netbeans/pull/1064[PR-1064 steps]. [...]
+
+[source,bash,subs="{markup-in-source}"]
+----
+
+$ hg update -C releaseXY_fcs
+$ ant clean
+$ ant build
+$ ant gen-sigtests-release
+$ hg st|cut -c 3-| xargs zip /tmp/sig.zip
+
+----
+
+The last target will modify a lot of module/nbproject/*.sig files and possibly generate some new. These files shall be integrated into trunk build. For example by:
+
+[source,bash,subs="{markup-in-source}"]
+----
+
+$ cd <team-repository>
+$ hg update -c default
+$ unzip /tmp/sig.zip
+$ hg add .
+$ hg ci -m "Signatures as of release X.Y"
+$ hg push
+
+----
+
+
+[[Check_for_Incompatible_Changes_Since_Previous_Version]]
+== Check for Incompatible Changes Since Previous Version
+
+There is another check for API signature compliance: A check that the APIs are compatible with a previous released version. This check is available to every module, which can make it part of its build by generating its API snapshot by:
+
+[source,bash,subs="{markup-in-source}"]
+----
+
+ant netbeans gen-sigtest
+
+----
+
+This creates a file nbproject/org-netbeans-module-name.sig which can be checked into the version control system as a reference point. This check is part of continuous build as well: every module with its golden file in nbproject/org-netbeans-module-name.sig is checked for backward compatibility and failures are included in continuous build link:http://deadlock.netbeans.org/hudson/job/trunk/lastBuild/testReport/[test results]. To run the same test for one module on local computer just use:
+
+[source,bash,subs="{markup-in-source}"]
+----
+
+$ ant netbeans check-sigtest
+
+----
+
+in your module directory and API of your module will be verified. Of course, only if the signature file exists.
+
+
+[[Who_needs_the_Golden_Signature_File]]
+=== Who needs the Golden Signature File
+
+Not every module with an API needs this golden file; currently only those modules that produced a stable API in release 6.1 have it. The plan is to update these golden files with a new version as soon as it is released, so future checks are done against latest released version.
+
+If an incompatible change is made (discouraged and subject to link:http://openide.netbeans.org/tutorial/reviews[API review process]) the golden file needs to be edited by hand to remove the element that is no longer present in the API.
+
+
+[[Checking_for_all_changes_from_previous_release]]
+== Checking for all changes from previous release
+
+In case you have the sig file in nbproject directory generated at the time of previour release (all public APIs have it), you can see all changes since that time by:
+
+[source,bash,subs="{markup-in-source}"]
+----
+
+$ ant -f yourmodule/build.xml check-sigtest -Dsigtest.check.type=strictcheck
+
+----
+
+
+[[apitest_tool]]
+=== apitest tool
+
+This check for incompatibilities is done by link:APITest.asciidoc[NetBeans' own version] of an OpenJDK tools. This adds a standard Ant task to check for binary backward compatibility, mutual signature compatibility. The binary compatibility check ignores generic types. Its link:http://hg.netbeans.org/apitest/[sources] are distributed together with its Mercurial repository and are available under GPL version 2. Builds are available from our link:http://deadlock.netbeans.org/hudson/job/api [...]
+
+
+[[Other_NetBeans_Tests]]
+=== Other NetBeans Tests
+
+* link:FindBugsTest.asciidoc[FindBugsTest]
+
+
+[NOTE]
+====
+
+The content in this page was kindly donated by Oracle Corp. to the
+Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/SignatureTest[http://wiki.netbeans.org/SignatureTest] ,
+that was last modified by NetBeans user Jtulach
+on 2018-12-31T04:42:32Z.
+
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
+
diff --git a/netbeans.apache.org/src/content/wiki/TaskDashboardDesignSpec.asciidoc b/netbeans.apache.org/src/content/wiki/TaskDashboardDesignSpec.asciidoc
new file mode 100644
index 0000000..72a6c13
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/TaskDashboardDesignSpec.asciidoc
@@ -0,0 +1,134 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+= TaskDashboardDesignSpec
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: Specification for the look and feel
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+[[Description_of_this_document]]
+== Description of this document
+
+This document is intended to serve as a specification for the look and feel,
+the features and functionality, and the user interaction with the proposed Task
+Dashboard window in Netbeans.
+
+
+[[Look_and_Feel]]
+== Look and Feel
+
+The base look and feel of the Task Dashboard is shown here:
+
+image:Task_Dashboard_MarkedUp.png[]
+
+
+[[User_Interface_Description]]
+=== User Interface Description
+
+
+[[General]]
+==== General
+
+The general User Interface is that of a dockable window. The intent is to
+provide a common location where developers can organize, access, and manipulate
+issues coming out of various Issue Trackers like Jira or Bugzilla.
+
+
+[[Description_of_UI_Aspects]]
+==== Description of UI Aspects
+
+Here are descriptions of the UI Aspects shown in the mockup above, based on the
+numerical callouts shown therein:
+
+1. Categories: Categories are user-created buckets into which individual issues can be placed. These can be for priority, due date, area of functionality, severity, or any other delineation that the user wants to segment their issues by. Once categorized, issues will appear in this area until the user removes them, or they can be filtered out once closed.
+. Repositories: Each Issue Tracker which is registered in NetBeans is given a top-level node in the Repositories tree. While it is assumed there might only be one or two, the proposal is to break it up by connection. There is also the notion of local tasks, that is, tasks that are created by the developer outside of any given repository, and kept private. More details on local tasks are link:TaskFocusedLocalTasks.html[here].
+. Queries: For each repository, there are various subnodes which map to a named/saved query upon that Issue Tracker. Users might set up a few named queries that organize their issues by various parameters and attributes. In each case, the Dashboard shows the total number of results as well as the number of issues that have changed in some way. These changed issues are shown at the top in blue text. Each issue is then shown as a subnode to the query and can be clicked to show or edit [...]
+. Repository Operators: There are four functions related to repositories. From right to left, they are:
+
+* Create New Task: creates a new issue using the parameters specific to the given repository.
+* Search in Repository: gives ability to query the repository. From here, you can create new named queries.
+* Refresh: re-runs all named queries to update results and status.
+* Close: closes the connection to the issue repository and removes it from the tree.
+
+. Filtering: There are two ways to globally filter the task dashboard. These filters will apply to the issues that appear both in Categories as well as in the Repository Query Results. The first filter is a dynamic text filter, shown as a text box. As you enter letters into this textbox, they are highlighted in relevant results, and non-matching results disappear. The numbers for results and changed also update to show the number of matches based on the current query. The second cap [...]
+
+image:Filter_Menu.png[]
+
+Notes on "Status": The idea behind status is that there will be the ability to
+specify, on a repository-by-repository basis, which statuses equate to "open"
+and which to "closed", since different Issue Trackers have different notions of
+these statuses (e.g. "resolved", "fixed", "completed).
+
+
+
+. Query Results: The query results show up both as summary text (i.e. the number of results and number of changed issues), as well as individual nodes that can be opened, edited, and/or categorized. Users can also schedule an issue, that is, give it a due date which can be used to organize or filter it later. It is also possible to right-click the Repository and group results by relevant attributes like priority:
+
+image:Group_Priority.png[]
+
+
+
+. When issues, categories, and repositories are "closed", they are shown as disabled and cannot be toggled open. They are sorted to the bottom of their respective lists. Notifications and auto-refresh are disabled for the closed items. Closed items can be filtered out using the filter shown in #5, at the top right of the dashboard.
+
+
+
+. New Category: New Categories can be created from here. Clicking this button launches a dialog that allows the user to provide a new name for their category.
+
+
+
+. New Repository: Launches the new Issue Tracker dialog for adding a new repository connection.
+
+
+[[Local_Tasks]]
+==== Local Tasks
+
+A category has the ability to show "Local Tasks", that is, tasks that are not pulled in from a repository. These can be created by an individual developer, assigned a schedule, and associated with other tasks as super- or sub-tasks. The only metadata available for a local task is the same as the "private" information available for any other task.
+
+
+[[Context_Menus]]
+==== Context Menus
+
+Each of the elements in the Task Dashboard have context menus associated with them. These are shown here:
+
+image:TaskDashboard_Menus.png[]
+
+Note on Repository Grouping: Each repository can supply, by API call, a set of grouping parameters. Likely parameters are "Priority", "Severity", or project area/module. Grouping is done via context menu. When grouped, each named query node will have subnodes for each value of the grouping parameter, under which the relevant query results will be shown.
+
+
+[NOTE]
+====
+
+The content in this page was kindly donated by Oracle Corp. to the
+Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/TaskDashboardDesignSpec[http://wiki.netbeans.org/TaskDashboardDesignSpec] ,
+that was last modified by NetBeans user RichGunther
+on 2012-05-10T19:15:28Z.
+
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
+
diff --git a/netbeans.apache.org/src/content/wiki/TaskDashboard_Menus.png b/netbeans.apache.org/src/content/wiki/TaskDashboard_Menus.png
new file mode 100644
index 0000000..a7f5936
Binary files /dev/null and b/netbeans.apache.org/src/content/wiki/TaskDashboard_Menus.png differ
diff --git a/netbeans.apache.org/src/content/wiki/TaskManagementUseCases.asciidoc b/netbeans.apache.org/src/content/wiki/TaskManagementUseCases.asciidoc
new file mode 100644
index 0000000..2f07937
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/TaskManagementUseCases.asciidoc
@@ -0,0 +1,569 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+= TaskManagementUseCases
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: Tasks Management
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:experimental:
+
+Use-case specification for the Task Dashboard window and related parts of Task-Focused NetBeans project.
+
+See also link:TaskFocusedNetbeansRequirements.asciidoc[Requirements]
+
+[[Tasks_Management]]
+== Tasks Management
+
+Use-cases related to tasks, repositories and queries management.
+
+
+[[User_Interface]]
+=== User Interface
+
+
+[[Show_Tasks]]
+==== Show Tasks
+
+*Actor:* User
+
+*Action:* Present user interface (Task Dashboard view) containing tasks and queries to the user. Tasks are organized into user-specified categories or by specified schedule dates.
+
+*Priority:* 1
+
+*Scenario:*
+
+* When the user opens the Task Dashboard view a list of tasks and queries is presented
+
+
+[[Basic_Tasks_Management]]
+== Basic Tasks Management
+
+
+[[New_Task]]
+=== New Task
+
+*Actor:* User
+
+*Action:* Create a new task
+
+*Priority:* 1
+
+*Scenario:*
+
+* User selects 'create new task' action
+* User selects a repository
+* Task is created and opened in an editor window
+
+
+
+
+[[Edit_Task]]
+=== Edit Task
+
+*Actor:* User
+
+*Action:* Open task in an editor window to edit its attributes
+
+*Priority:* 1
+
+*Scenario:*
+
+* User selects 'Open Task' item in context menu of the task (or double-click on it - probably)
+* New window in editor is opened and the user can review or edit attributes of the task
+
+
+
+
+[[Add_Task]]
+=== Add Task
+
+*Actor:* User
+
+*Action:* Add existing task to the Task Dashboard view
+
+*Priority:* 1
+
+*Scenario:*
+
+* User finds the task he wants to add (see link:TaskFocusedNetBeansUseCases.asciidoc#Search_in_Repository.asciidoc[Search in Repository use-case])
+* The user adds the task to the Task Dashboard view by using the 'Add to Task Dashboard' action on selected task
+
+
+
+
+[[Remove_Task]]
+=== Remove Task
+
+*Actor:* User
+
+*Action:* Remove task from the Task Dashboard view
+
+*Priority:* 1
+
+*Scenario:*
+
+* User selects the 'Remove from Task Dashboard' item in the context menu of the task (or shortcut 'delete')
+* The task is removed from the Task Dashboard view (only the Task Dashboard entry, not the issue in repository)
+
+
+
+
+[[Activate_Task]]
+=== Activate Task
+
+*Actor:* User
+
+*Action:* Activate a task and deactivate the previous one. Only one task can be activated
+
+*Priority:* 1
+
+*Scenario:*
+
+* User selects 'Activate' item in the context menu of the task
+* Selected task is activated and the IDE properly reflects the context of the task.
+
+_TODO: add link to the Context use-case which describes how the IDE reflects to it_
+
+
+[[Deactivate_Task]]
+=== Deactivate Task
+
+*Actor:* User
+
+*Action:* Deactivate a task
+
+*Priority:* 1
+
+*Scenario:*
+
+* User selects the 'Deactivate' item in the context menu of the task
+* Selected task is deactivated
+
+_TODO - what happen after deactivation, how does the IDE reflects to it_
+
+
+[[Advanced_Tasks_Management]]
+== Advanced Tasks Management
+
+
+[[Filter_Tasks]]
+=== Filter Tasks
+
+*Actor:* User
+
+*Action:* The user can filter tasks in the Task Dashboard view.
+
+*Possible usages:*
+
+* The user wants to see only uresolved (opened) tasks in the Task Dashboard so he sets filter on 'Show unresolved only' (probably default setting) or he needs to deal with an already resolved task so he switches to the 'Show all' filter.
+
+*Priority:* 3
+
+*Scenario:*
+
+
+
+
+[[Quick_Search]]
+=== Quick Search
+
+*Actor:* User
+
+*Action:* Perform a quick search over tasks in the Task Dashboard or in a repository
+
+*Possible usages:*
+
+* The user filters tasks using string NullPointerException in summary to find and eliminate tasks reporting the same exception or enter a part of the know summary to find the task faster.
+
+*Priority:* 3
+
+*Scenario:*
+
+* User selects the 'Quick Search' action and fills in search parameter.
+* Search results are presented to the user
+* User can open a task from a search result or perform new search
+
+
+
+
+[[Add_Private_Note]]
+=== Add Private Note
+
+*Actor:* User
+
+*Action:* Add a private note to a task. Added note is not reflected in the original issue.
+
+*Priority:* 3
+
+*Scenario:*
+
+* During the *Edit Task* use case user edits the 'Private note' attribute of the task
+
+
+
+
+[[Sort_Tasks]]
+=== Sort Tasks
+
+*Actor:* User
+
+*Action:* User is able to sort tasks in the Task Dashboard view by various parameters (summary, priority,...)
+
+*Priority:* 4
+
+*Scenario:*
+
+_TODO - general UI structure for sorting_
+
+
+
+[[Offline_Mode]]
+=== Offline Mode
+
+*Actor:* User
+
+*Action:* Task changes can be stored locally and the user doesn't have to submit every change to the task repository. It allows the user to work offline.
+
+*Priority:* 4
+
+*Scenario:*
+
+
+[[Organize_Tasks]]
+== Organize Tasks
+
+
+[[Create_Category]]
+=== Create Category
+
+*Actor:* User
+
+*Action:* Create new category in the Task Dashboard view
+
+*Priority:* 1
+
+*Scenario:*
+
+* User select the 'New Category' action
+* Dialog window pops up, user specifies the name of the category and confirms creation by selecting 'Create' action
+* Category is created and shown in the Task Dashboard view
+
+
+
+
+[[Delete_Category]]
+=== Delete Category
+
+*Actor:* User
+
+*Action:* Delete category from the Task Dashboard view
+
+*Priority:* 1
+
+*Scenario:*
+
+* User chooses category he wants to remove and selects 'Remove' action
+* In case the category isn't empty the confirmation dialog pops up waiting for user to confirm deletion. Otherwise the category is deleted without confirmation.
+* The category is deleted from the Task Dashboard. Tasks contained in the category are also removed.
+
+
+
+
+[[Rename_Category]]
+=== Rename Category
+
+*Actor:* User
+
+*Action:* Rename category
+
+*Priority:* 2
+
+*Scenario:*
+
+* User selects 'Rename' action for the category
+* Dialog window pops up, user specifies the name of the category and confirm rename selecting 'Rename' action
+* The category is renamed
+
+
+
+
+[[Add_Task_to_a_Category]]
+=== Add Task to a Category
+
+*Actor:* User
+
+*Action:* Set category of a task
+
+*Priority:* 1
+
+*Scenario:*
+
+_Note: few possibilities how to achieve this_
+
+* User selects 'Set Category' action for the task
+* From the presented list of existing categories user selects one
+* Task is moved to the selected category
+
+_TODO: can be one task in several categories?_
+
+* User sets category of the task using Drag-and-Drop mechanism in the Task Dashboard view
+
+
+[[Schedule_Task]]
+=== Schedule Task
+
+*Actor:* User
+
+*Action:* Set schedule date, due date and estimated time to complete task
+
+*Priority:* 2
+
+*Scenario:*
+
+* The user can edit 'Schedule date', 'Due date' or 'Estimated time' attributes of the task as a part of link:TaskFocusedNetBeansUseCases.asciidoc#Edit_Task[Edit Task use-case]
+
+
+[[Repositories_Management]]
+== Repositories Management
+
+
+[[Add_Repository]]
+=== Add Repository
+
+*Actor:* User
+
+*Action:* Add supported repository
+
+*Priority:* 1
+
+
+[[Remove_Repository]]
+=== Remove Repository
+
+*Actor:* User
+
+*Action:* Remove repository
+
+*Priority:* 1
+
+
+[[Edit_Repository]]
+=== Edit Repository
+
+*Actor:* User
+
+*Action:* Edit properties of repository
+
+*Priority:* 1
+
+
+[[Search_in_Repository]]
+=== Search in Repository
+
+*Actor:* User
+
+*Action:* User wants to search a given repository to find
+
+*Possible usages:* Find a new issue by ID or all issues assigned to the user. This functionality can by used to add tasks and queries into the Task Dashboard view.
+
+*Priority:* 2
+
+*Scenario:*
+
+* User opens the search window using the 'Search' action.
+* User selects the repository he wants to search in
+* User specifies parameters of the search (query) and confirms it
+* Query is performed and its result are presented to the user
+* (Optional) User can select tasks from the result and add them to the Task Dashboard view or add the whole query eventually.
+
+
+
+[[Show_Repositories]]
+=== Show Repositories
+
+*Actor:* User
+
+*Action:* Show a list of existing repositories
+
+*Priority:* 1
+
+*Scenario:*
+
+
+[[Queries]]
+== Queries
+
+
+[[Create_Query]]
+=== Create Query
+
+*Actor:* User
+
+*Action:* Create a query on selected repository
+
+*Priority:* 2
+
+*Scenario:*
+
+* User specifies a query with requested parameters (see the link:TaskFocusedNetBeansUseCases.asciidoc#Search_in_Repository[Search in Repository use-case])
+* Using the 'Add query to Task Dashboard' action user adds the query to the Task Dashboard view
+
+
+
+[[Edit_Query]]
+=== Edit Query
+
+*Actor:* User
+
+*Action:* Edit parameters of a query
+
+*Priority:* 2
+
+*Scenario:*
+
+* User selects 'Edit' action for the query
+* User respecifies parameters of the query and confirm changes
+
+
+
+[[Show_Query_Result]]
+=== Show Query Result
+
+*Actor:* User
+
+*Action:* Show the result of a query
+
+*Priority:* 2
+
+*Scenario:*
+
+_TODO - How to present query results? In Task Dashboard view or using current query window?_
+
+
+
+
+[[Remove_Query]]
+=== Remove Query
+
+*Actor:* User
+
+*Action:* Remove a query from Task Dashboard view
+
+*Priority:* 2
+
+*Scenario:*
+
+* User selects the 'Remove' action for the query
+* The query is removed from the Task Dashboard view
+
+
+[[Notifications]]
+== Notifications
+
+
+[[Remote_Changes_Notification]]
+=== Remote Changes Notification
+
+*Actor:* IDE
+
+*Action:* IDE informs the user about changes to a task or about new tasks
+
+*Priority:* 3
+
+*Scenario:*
+
+* When changes to a task or new tasks appear, notification is shown.
+
+
+
+
+[[Schedule_or_Due_date_Notification]]
+=== Schedule or Due date Notification
+
+*Actor:* IDE
+
+*Action:* IDE informs user about the upcoming schedule or due date of tasks
+
+*Priority:* 3
+
+*Scenario:*
+
+* When approaching the schedule or the due date of a task, a notification describing relevant tasks is presented to the user
+
+
+
+
+[[Synchronization]]
+== Synchronization
+
+Synchronization covers pulling changes from a task repository and also pushing locally changed tasks.
+
+_TODO: do we want to push only submited tasks or all locally changed tasks?_
+
+
+[[Synchronize_Tasks_Manually]]
+=== Synchronize Tasks Manually
+
+*Actor:* User
+
+*Action:* Synchronize tasks in the Task Dashboard view with their remote sources manually.
+
+*Priority:* 1
+
+*Scenario:*
+
+* User can synchronize single tasks or whole categories/queries/repositories using the 'Refresh' action in the context menu of those items
+
+
+
+
+[[Synchronize_Tasks_Automatically]]
+=== Synchronize Tasks Automatically
+
+*Actor:* IDE
+
+*Action:* Synchronize tasks in the Task Dashboard view with their remote sources automatically.
+
+*Priority:* 3
+
+*Scenario:*
+
+* Tasks contained in the Task Dashboard view are synchronized automatically in the user defined period. The synchronization only start when the Dashboard in not in use (prevent refreshing while user is working with the dashboard)
+
+
+
+[NOTE]
+====
+The content in this page was kindly donated by Oracle Corp. to the
+Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/TaskManagementUseCases[http://wiki.netbeans.org/TaskManagementUseCases] ,
+that was last modified by NetBeans user JPESKA
+on 2012-06-14T08:57:58Z.
+
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/Task_Dashboard_MarkedUp.png b/netbeans.apache.org/src/content/wiki/Task_Dashboard_MarkedUp.png
new file mode 100644
index 0000000..9aa217a
Binary files /dev/null and b/netbeans.apache.org/src/content/wiki/Task_Dashboard_MarkedUp.png differ
diff --git a/netbeans.apache.org/src/content/wiki/VersioningPolicy.asciidoc b/netbeans.apache.org/src/content/wiki/VersioningPolicy.asciidoc
new file mode 100644
index 0000000..14f10e2
--- /dev/null
+++ b/netbeans.apache.org/src/content/wiki/VersioningPolicy.asciidoc
@@ -0,0 +1,315 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+
+= VersioningPolicy
+:jbake-type: wiki
+:jbake-tags: wiki, devfaq, needsreview
+:markup-in-source: verbatim,quotes,macros
+:jbake-status: published
+:syntax: true
+:description: NetBeans - API & Module Versioning Policy
+:icons: font
+:source-highlighter: pygments
+:toc: left
+:toc-title:
+:toclevels: 5
+:experimental:
+
+If there were no external modules that could run on NetBeans, and we did not
+have the Update Center to let users mix and match modules, then handling
+versioning in NetBeans would be very easy: nothing more than labelling when
+every module was built.
+
+However, we _do_ have these concerns. So some guidelines are required to make
+sure that the module versioning system is capable of matching our practice.
+
+Issues include labelling of APIs according to version numbers; specifying
+levels of compatibility; depending on other modules; marking releases for Auto
+Update; providing APIs from modules; and so on.
+
+See also link:CompatibilityPolicy.asciidoc[CompatibilityPolicy].
+
+
+[[Versioning_of_APIs]]
+== Versioning of APIs
+
+The link:http://bits.netbeans.org/dev/javadoc/org-openide-modules/org/openide/modules/doc-files/api.html[Modules API] includes a detailed description of how versions and dependencies work
+technically. This documented is intended to give a policy for how to use them
+on netbeans.org.
+
+[[What_is_an_API_change.3F]]
+== What is an API change?
+
+The simplest case of an API change is anything that changes the public or
+protected signature of a public or protected class, that is a signature change
+which would appear in Javadoc and possibly affect clients of the API. These may
+be compatible or not, depending on whether any client code would be required to
+change in order to continue to run in binary form; and in order to compile in
+source form. Note that changing the set of unchecked exceptions documented to
+be thrown by a method, or changing whether a method is permitted to accept or
+return `null`, counts as an API change and may be compatible or not.
+
+More subtle changes include behavioral changes where the behavior is specified
+in API documentation. For example, if a method is documented to call some other
+protected method inside its dynamic scope while holding a particular lock,
+ceasing to hold that lock or ceasing to call that other method would be an API
+change, potentially incompatible. These kinds of changes are harder to
+evaluate, so be careful to read the existing documentation; and when adding new
+documentation be careful to say exactly what you intend the behavior to be, and
+if the documentation includes anything that you expect could change and should
+not be relied on, say so. For example:
+
+[source,java,subs="{markup-in-source}"]
+----
+
+/**
+ * Open this widget.
+ * Will be called while holding widget control lock.
+ * <p>In the current implementation, this uses {@link #createWidget}
+ * but that may be changed in the future.
+ * @return the opened widget
+ */
+----
+
+
+[[How_to_make_an_API_change]]
+== How to make an API change
+
+API changes must not only be documented, they must also be matched to API versioning, so module authors can programmatically depend on them.
+
+
+[[Compatible_change_on_the_trunk]]
+=== Compatible change on the trunk
+
+The safest possible sequence of steps for making a _backwards-compatible_ API change is this:
+
+
+
+1. Go through link:APIReviews.html[APIReviews] and get approval for the change.
+. Make sure you have a _CVS working directory_ of the appropriate module(s) checked out - do not commit changes until later. Do not make changes in client module code to use the new API yet, if you were planning to - at least keep a copy of the existing module source for the IDE. This is to ensure that a standard set of modules continues to work with the changed API without themselves being changed.
+. Make the change in your working copy of sources. If the change adds a new class, method, etc. which will be visible in Javadoc (public or protected), or changes the behavior of a documented object, please make sure you document what it is supposed to do in Javadoc (its contract, not details of implementation).
+. Increase the specification version in your module's manifest. If the previous version was `1.3`, change it to `1.4`, i.e. always increase the last number in the version. Remember that the version after `1.9` is `1.10`, _not_ `2.0`.
+. If the API change involved adding a class, method, etc. to the APIs that will appear in Javadoc, add a `@since` tag mentioning the new module name and specification version. For example: @since org.netbeans.modules.foo/1 1.4. If the documented behavior of an existing object is being changed, mention this as well, for example: @since org.netbeans.modules.foo/1 1.3; as of 1.4, resulting list may also be modified. If an object is deprecated, say when, e.g. @deprecated As of org.netbeans.m [...]
+. If there is prose API documentation describing the API you are modifying at a higher level, please consider updating this as well, if it needs it.
+. Use *Build | Generate Javadoc* from the IDE to build documentation for the module and view it. Look over the changed docs.
+. Update your apichanges.xml to mention the new API change. Insert an entry with the appropriate API and class name, label it with the date and new specification version, and give a description of the change and any suggestions for how or why to use it.
+. Build and test the whole IDE - note this is with the API change made but no one yet using it.
+. For changes in client modules to use the new API, see below.
+. Run cvs diff to *verify all changes*. If the output is messy and hard to understand (e.g. unrelated parts of code reformatted for no reason), stop! Revert all unneeded changes, and again build and test the IDE, and diff again.
+. Commit the API change in *one CVS commit*: all affected source files, the changed manifest, apichanges.xml, and any other affected documentation.
+
+
+[[Compatible_change_on_a_branch]]
+=== Compatible change on a branch
+
+For changes made on experimental branches to test whether a new API can support other development on that branch, there are no special requirements: change what you like, but remember to follow the steps listed above when merging into the trunk.
+
+API changes in release (stabilization) branches are *discouraged* and should only be made when they are required for some priority bugfix. They should of course be made in the trunk as well. The procedure is similar to that listed above for trunk changes; however:
+
+* You will be creating a different specification version on the branch, e.g. `1.3.3` from `1.3.2`.
+* Mention both the branch and trunk versions in all places where a version number is requested above. E.g. @since 1.4 and 1.3.3.
+
+
+[[Incompatible_change]]
+=== Incompatible change
+
+Of course you should avoid making incompatible API changes unless really necessary. But, if you do, do it right. Do all steps needed for compatible changes, and also:
+
+
+
+1. Make sure you have an API review that authorized the incompatible change.
+. Increase the major release number in the module's manifest; for example your code name could change from org.netbeans.modules.foo/1 to org.netbeans.modules.foo/2. The specification version should conventionally be increased e.g. from 1.10 to 2.0 as a mnemonic.
+. If there are any other modules on netbeans.org which depend on your module's API, change them as well in source. Ask for help from other module owners as needed, but _you_ must make the physical change.
+. Build and test the whole IDE, from scratch (clean build), and be careful.
+. Commit all changes (to your module and to other modules depending on it) in one CVS commit.
+. Notify dev@openide.netbeans.org of the change, and how clients of your module's API should be changed to work with the new version.
+
+[[How_to_use_an_API_change]]
+== How to use an API change
+
+A module should in general explicitly declare the version of every API-providing module it requires in its manifest. It is a developer's responsibility to maintain the accuracy of this dependency at all times. For example, your project.xml might list:
+
+[source,xml,subs="{markup-in-source}"]
+----
+
+<dependency>
+ <code-name-base>org.apache.tools.ant.module</code-name-base>
+ <build-prerequisite/>
+ <compile-dependency/>
+ <run-dependency>
+ <release-version>3</release-version>
+ <specification-version>3.12</specification-version>
+ </run-dependency>
+</dependency>
+----
+
+to request version 3.12 or higher of the Ant module API. The IDE will forbid a user to install it if an older version of the Ant module is present (or if the module is missing altogether).
+
+If you have made a compatible API change according to the steps above, you may now use it in your module. Make any code changes to use the new API. Also change your project.xml to require the new version. Build and test the IDE including your module with its new changes, run cvs diff, and commit the code changes and project.xml in one CVS commit.
+
+Avoid increasing your dependency on the API version arbitrarily, as it would prevent a user interested in trying out a new version of your module from running it in an older build (such as the last release version). Of course, if you are not sure which new APIs you might be using, to be safe request the newest API version.
+
+
+[[Providing_a_module_API]]
+== Providing a module API
+
+In order to provide an API from your module for the use of other modules, please follow these steps:
+
+
+
+1. Make sure your module code name has a major release version. For example, OpenIDE-Module: org.netbeans.modules.foo/1. This ensures you have a mechanism for indicating any incompatible changes later. If you forget, no major release version is similar to -1.Convention is to initially use /0 for a freshly introduced API. Clients should depend on your.module/0-1. If you stabilize it in a subsequent release, change it to /1. If you find it was mistaken and have to break compatibility in a [...]
+. Make sure your module declares a specification version. For example, OpenIDE-Module-Specification-Version: 1.7. (You should use the *Versioning* tab of your project properties to manage this.)
+. Decide on some subset of your module's classes that will form an API. Clearly the smaller and simpler this subset, the better.
+. Place all API-related classes into a special package or package structure in your module that is clearly distinguished from the rest. The convention is to name the package to include `api` or `spi`, and to indicate degree of binding to the module implementation. For example, if the private implementation of your module is in `org.netbeans.modules.foo` (and subpackages), you may use these packages (and their subpackages):
+`org.netbeans.api.foo`:: Client APIs for the general functionality you provide. Such APIs are assumed to not be closely tied to the implementation of your module, i.e. a quite different implementation could in principle (or fact) support them.
+`org.netbeans.spi.foo`:: As above, but service-provider APIs, and supports (common implementation bases and defaults). You may wish to host support classes separately from "pure" SPIs.
+`org.netbeans.modules.foo.api`:: Client APIs which are bound in meaning to specific services your module provides. Consider exposing these only as a "friend" API to a selected set of modules.
+`org.netbeans.modules.foo.spi`:: As above, but service-provider APIs.
+. Physically restrict other modules from using packages outside your API area; see the Modules API for details on how to do this. Use `<public-packages>` or `<friend-packages>` in your project.xml.
+. Write clear and complete Javadoc comments for all publically accessible members in the API package.
+. If additional specifications of module behavior beyond the Javadoc are necessary, use `package.html` and/or `doc-files/*.html` as needed. You can keep such documentation in your main source tree if you like. samples/ or some such subdirectory can contain example code demonstrating use of the API.
+. Keep an `apichanges.xml` file, listing specification versions, dates, and changes made. If registered in `project.properties` it will be automatically displayed in your module's Javadoc.
+. Make sure your module's API is published in `nbbuild/build.properties`.
+
+
+[[Keeping_track_of_API_changes]]
+== Keeping track of API changes
+
+Each module should have an apichanges.xml and list of generated changes in order to track the progress of development of its APIs. Here are the steps you should take to get such list:
+
+
+
+1. Copy nbbuild/javadoctools/apichanges-template.xml to your own module, e.g. foo/apichanges.xml.
+. Replace all CHANGEME strings with the correct path or token.
+. Edit your apichanges.xml:
+. edit <apidefs> as needed (your module might have only one API area)
+. add <change>s
+. Generate Javadoc for the module and check it.
+
+
+[[Upgrade_Guide]]
+=== Upgrade Guide
+
+Significant changes in APIs which require the attention of users of your API should be documented in a separate Upgrade Guide document: currently there is only one, at openide/api/doc/org/openide/doc-files/upgrade.html. The document should summarize what is necessary to do to switch to a new API, what are the advantages of using the new API, performance implications, etc.
+
+
+[[Using_a_module_API]]
+== Using a module API
+
+To use another module's API in your module, you must declare a dependency on that module in your project.xml. Now you may import and use API classes from the "foo" module in your module's code, e.g. `org.netbeans.api.foo.FooCookie`. Use of non-API classes is not permitted as your module might break unexpectedly.
+
+If the "foo" module adds new APIs in version 1.8 which you wish to use, you must increase your dependency in the manifest to 1.8 at the same time as you make code changes to use the new APIs, and commit these together in one CVS commit. If the "foo" module changes incompatibly to e.g. org.netbeans.modules.foo/2 1.0, it will be necessary to make any needed code changes in your module, as well as to change project.xml.
+
+Calling ((ClassLoader)Lookup.getDefault().lookup(ClassLoader.class)).loadClass("some.other.modules.Class") to use classes from a module you do not declare a dependency on is strongly discouraged - in some cases it will work, in others it will not. In general use of reflection between modules is a poor idea, and there is generally a cleaner (and simpler) solution. Do not be afraid to split your module into a general half, and a half which additionally depends on some other module and uses [...]
+
+
+[[Versioning_of_user_data]]
+== Versioning of user data
+
+As a rule, modules should be very careful to ensure that data stored by a user is not corrupted by newer versions of a module. Settings, as opposed to development data, are generally not expected to be preserved without errors when downgrading to older versions of a module.
+
+
+[[Serialized_settings]]
+=== Serialized settings
+
+Modules storing any settings in serialized form should pay attention to compatibility of these settings. Use `serialVersionUID` for all serializable classes, and do not change it once set. Newer versions of a module must be able to read settings stored by older versions without user-visible errors, as a rule of thumb. If a class is no longer needed except for deserialization, remove any unnecessary methods, @deprecate it, and if applicable return `null` from `readResolve` so it will be ignored.
+
+Remember, common serializable objects include: `SystemOption`s; `ServiceType`s (now rarely used); `TopComponent`s; `Node.Handle`s (usually only a concern for creators of top-level nodes in their own windows); `.Env` environments from open and edit supports; and `DataLoader`s. There are some other serializable things but these are the ones you will commonly deal with.
+
+Helpful mechanisms for making serialized forms of objects more robust include implementing `Externalizable` and writing state in a specific order, to reduce the amount of information written; keeping state in a hashtable rather than direct nontransient instance variables, which makes it easier to recover from missing fields, and handle new ones; and using versioned serialization replacers, each version of which reads its own format from settings and constructs the current in-memory repre [...]
+
+
+[[Non-serialized_settings]]
+=== Non-serialized settings
+
+If you store settings in some other way - for example, XML files in the system folder - then you are responsible for maintaining compatibility of them however is appropriate. This may be easier than for serialized settings, since old and inapplicable settings objects can be simply ignored.
+
+
+[[XML_DTDs_and_Schemas]]
+=== XML DTDs and Schemas
+
+Many modules have a need to specify XML DTDs or XML Schemas to store various kinds of information - commonly objects provided by modules in XML layers, or stored as part of user settings. Basic rules for creating a schema:
+
+
+
+1. Define your schema, and choose an initial version for it. Store the schema inside your module somewhere, e.g. org/netbeans/modules/foo/resources/foodata-1.xsd.
+. Choose a public ID for the DTD. This *must* mention the version number in it, mention NetBeans or somehow indicate what part of the world this applies to, and be more rather than less descriptive. For example:
+[source,java,subs="{markup-in-source}"]
+----
+
+-//NetBeans//DTD Foo Widget Configuration 1.0//EN
+----
+
+XML Schemas use URIs instead. For XML Schema, include the version number in the namespace, e.g. link:http://www.netbeans.org/ns/foodata/1[http://www.netbeans.org/ns/foodata/1].
+
+1. DTDs may be registered in /xml/entities/ in your XML layer, for use in XML completion. XML Schemas currently cannot.
+. Decide on a public URL for the DTD, such as link:http://www.netbeans.org/dtds/foodata-1_0.dtd[http://www.netbeans.org/dtds/foodata-1_0.dtd]. This *must* mention the version number. For XML schema, perhaps just append .xsd to the URI, e.g. link:http://www.netbeans.org/ns/foodata/1.xsd[http://www.netbeans.org/ns/foodata/1.xsd].
+. Place a copy of the DTD/schema at this location (in source, www/www/dtds/ or www/www/ns/) so it will be accessible from the internet. Also modify the catalog file in this directory to mention it (for DTDs); or catalog.xml (for Schema).
+. It is a good idea to include inside the schema comments giving its public ID and public URL (for DTDs), as well as a brief description of what it is for.
+. All XML files based on a DTD should include an explicit `<!DOCTYPE>` tag, so that XML editing tools can reliably recognize and handle them. For XML Schema, it is only necessary to use the correct namespace; the `schemaLocation` attribute is not necessary.
+
+To make changes to a schema:
+
+1. *Never* change a schema (other than adding comments etc.) without changing the public ID / namespace!
+. Choose a public ID / namespace for the new version of the schema, say by incrementing the version number in the ID / namespace.
+. Add the new schema to your module's resources package. Leave the old one there.
+. Register the new schema in your module's layer, if applicable. Leave the old registration there.
+. Add the new schema to the netbeans.org schema publishing area. Leave the old schema there.
+. Make sure your module code is capable of reading and handling any version of the schema.
+
+
+[[Development_data]]
+=== Development data
+
+Development data should be handled much more carefully than settings. This means any data which the user has created which actually forms a part of the developed application, rather than configuration of the IDE. For example, *.form files used by the Form Editor. Certainly new versions of a module should be able to read data produced by any older version. It is also very desirable for older versions of the module to be able to read the format produced by the newer version of the module, [...]
+
+Modules with special file formats for development data should also use readable textual formats whenever possible, and give special consideration to avoiding unneeded formatting changes when saving, so that the data can be used in a textual version-control system comfortably.
+
+
+[[Numbering_Scheme_for_Updates]]
+== Numbering Scheme for Updates
+
+While developers have the responsibility to manage dependencies from their modules to both the Open APIs and other modules, and mark API changes of all sorts with changes in the module or API specification version, release engineers who publish modules also need to make version-number changes. Remember, it is never particularly harmful to increase the specification version (for example before cutting a release of a module), and either developers or release engineers may do so - such chan [...]
+
+It is recommended that API and module specification versions in the trunk follow a two-digit scheme such as 1.5, where the next in sequence would be 1.6. On a release branch, three-digit schemes should be used, such as 1.5.1, 1.5.2, and so on. Post-release patches could have four digits, and so on.
+
+If a number of API changes are made between releases, it may be annoying for the API specification version to be e.g. 1.133. Additionally, if specification versions of the APIs are to be used to distinguish the APIs available in each IDE release, they should be more mnemonic. So it may be useful to choose a new first digit after a release. For example, 1.20 may be branched for a release, forming 1.20.1 and so on, released as 1.20.4; meanwhile, the development builds become 2.1 rather tha [...]
+
+It is important that every published release of a module have a different specification version. Otherwise automated updates cannot work correctly. Of course, if a "new version" of a module is being published solely because it was included in some bugfix build, and in fact did not contain any user-noticeable changes from the last released version, release engineers may prefer to either avoid increasing its specification version, or withhold it from the update center altogether, so as to [...]
+
+Please remember that implementation versions of modules are not intended to be ordered. Implementation versions need not actually be numeric at all, and the IDE's Modules API _intentionally_ prevents inter-module dependencies from using them except as exact string comparisons. Specification versions, by contrast, must be numeric, and the only permitted comparisons in dependencies are of the form "version x.y.z or anything greater".
+
+As a practical policy for using implementation versions, it is helpful to make them integers if they are being used in implementation dependencies from other modules, and use the build property `spec.version.base` in both producers and consumers of implementation dependencies in place of a fixed specification version. This trick makes management of complex sets of modules with implementation dependencies much easier. From the NBM project GUI, just check the checkbox *Append Implementatio [...]
+
+Release engineers should assume that module manifests provide complete information about which versions of what module may be run on which version of the IDE, via their major release versions, specification versions, and dependencies. Of course these assumptions should also be tested before actually publishing something on a public update server; but if any inconsistencies are found, these are P1/P2 bugs *for the developer* and it is better to resolve them properly in the code, than to u [...]
+
+
+[NOTE]
+====
+
+The content in this page was kindly donated by Oracle Corp. to the
+Apache Software Foundation.
+
+This page was exported from link:http://wiki.netbeans.org/VersioningPolicy[http://wiki.netbeans.org/VersioningPolicy] ,
+that was last modified by NetBeans user Jglick
+on 2010-05-18T16:44:49Z.
+
+
+This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
+====
diff --git a/netbeans.apache.org/src/content/wiki/notification_FitnessViaPostMortem.png b/netbeans.apache.org/src/content/wiki/notification_FitnessViaPostMortem.png
new file mode 100644
index 0000000..a91e7e3
Binary files /dev/null and b/netbeans.apache.org/src/content/wiki/notification_FitnessViaPostMortem.png differ
diff --git a/netbeans.apache.org/src/content/wiki/yes.png b/netbeans.apache.org/src/content/wiki/yes.png
new file mode 100644
index 0000000..ba15628
Binary files /dev/null and b/netbeans.apache.org/src/content/wiki/yes.png differ
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@netbeans.apache.org
For additional commands, e-mail: commits-help@netbeans.apache.org
For further information about the NetBeans mailing lists, visit:
https://cwiki.apache.org/confluence/display/NETBEANS/Mailing+lists