add table of contents / outline / draft

Update README.adoc

Cleanup and re-org of setup dev environment page

add doc building/configuring_git_workflow.adoc and associated images

new image for PDE install

tweaks to Rob's building/setup_development_environment.adoc

update README to link to Rob's new
building/setup_development_environment.adoc; also make sections
hotlinkable

add marketplace install images

setup_development_environment.adoc moved into building/ folder

move CONTRIBUTING.adoc into building/CONTRIBUTING.adoc

move central and usage stuff into api folder

Update configuring_git_workflow.adoc

Add git user config and 'ch' alias

move issues -> community

fix links and case of titles to avoid the Wrath of Max (WoM)

Conflicts:
	README.adoc

Added hub reference to configuring dev-env

Rewriting target platform for consumers, convert to adoc

added title to tp-for-consumers

tweak target_platforms_for_consumers.adoc for content, consistent
spellings and layout

clean up index for 'Setting up the target platform' section

bold the left column and add valign/halign/frame/grid options

Finishing git workflow

Added testing local build file

link to all docs in the building/ folder from the README.adoc; replace
all .md files with .adoc; fix broken links/formatting

fix a couple typos

fix a couple typos

Fix debug options example

add section on keeping git repo clean / purging old topic branches

Testing a build

added an alias for cleanup remote

Added foundation API page

Reworking index to be more max-friendly

Added content for exporting plugin from eclipse

Added runtime workbench file, split up installing local build vs testing
local build

Added a link to max's updating version blog entry

add page re: remote debugging; link to it from multiple places so Rob
won't forget how to do it in future; new image w/ port 8000

update build options page to JBT 4.2/4.3; update build from eclipse page
to JBT 4.2

add pages about Tycho and commandline building; add more commandline
flags into building/build_options.adoc

clean up FAQ; reorder README/TOC; add more links to building via
commandline and in Eclipse; add note about deprecated -XX flags in JDK
8; add page explaining how to add test plugins/features and itest
plugins/features

add FAQ entry about libgtk missing .so (from Rob's recent debug session)

fix typo and add section about how to mirror requirements w/ build.xml
and jbosstools-requirements job

Cleanup of nick's recent patches

Adding a section on exposing and migrating API

Moving source stuff to its own folder

Tagging and Branching

Adding a section for third party libs

Changed a title to be more clear

minor tweaks & add TODO markers

add doc about code freeze process

add doc about update sites, and move two docs in building/ to source/

add doc about ading features to JBT/JBDS, Central, EA, and Marketplace

add release guide stub and remove TOC entry for 'documenting API' since
that's just done in the source

add new list_of_projects page (JBIDE-18846)

merge @mickael_istria's commit from Feb 10 into the new
target_platforms_for_consumers.adoc [695af23]

implement Max's suggestions / review of jbosstools#42

merge in Rob's changes from f763e27

Small typo

Remove deleted file

Author: robstryker

CONTRIBUTING.adoc

@@ -10,41 +10,41 @@ The layout of the current documentation is the following:
 - link:issues[] - how to use issue tracker, shared queries etc.
 - <your topic here> - if you feel an overall issue are missing, create a pull request (PR) and suggest one
 
-To contribute content simply edit live on http://github.com[github] webui or clone the repository and submit a pull-request.
+To contribute content, you can clone the repository and submit a pull request, or, you can click on the "pencil" icon to make changes directly. 
 
 Content guidelines
 ==================
 
-* Content should be for how to develop and/or contribute to JBoss Tools
-* Should not contain user guides for plugins functionallity unless that guide is needed for debugging/tracing/exploring the plugin. User guides are in each plugin or at http://github.com/jbosstools/jbosstools-documentation
-* Use asciidoc (.adoc) wherever possible, see http://asciidoctor.org/docs/asciidoc-quick-reference[Asciidoc quick reference] since it is more portable and has better features than Markdown. MarkDown is also ok if must be.
-* If you got existing content you want to convert to asciidoc http://johnmacfarlane.net/pandoc/[Pandoc] works great for almost any reasonable format (especially with https://github.com/jgm/pandoc/pull/868[this patch] applied)
-* use lowercase with _'s for space in filenames. (i.e. `how_to_contribute.adoc` is Good, 'How-To-Contribute.adoc' or 'howtocontribute.adoc' is Bad)
+* Content should be for how to contribute to or develop JBoss Tools
+* Should not contain user guides for individual plugin functionallity unless that guide is likely to be used or extended by many other components.  User guides for specific plugins should be placed in each plugin's documentation folder, or at http://github.com/jbosstools/jbosstools-documentation
+* Use asciidoc (.adoc).  See http://asciidoctor.org/docs/asciidoc-quick-reference[Asciidoc quick reference] as a guide to get up to speed with the syntax. 
+* If you have existing content that you want to convert to asciidoc, http://johnmacfarlane.net/pandoc/[Pandoc] works great for almost any reasonable format (especially with https://github.com/jgm/pandoc/pull/868[this patch] applied)
+* use lowercase filenames with underscores in place of a space character. (i.e. `how_to_contribute.adoc` is good, `How-To-Contribute.adoc` or `howtocontribute.adoc` is bad)
 
 GitHub Web vs local/git
 =======================
 
-There are two recommended ways to contribute to the documentation:
+There are two recommended ways to contribute to this documentation:
 
 - using the github web ui
 - offline local editing by cloning the repository. 
 
-You can do almost everything in both places, the main limitations of github web ui is that they currently do not support upload of images.
-The table below outlines the various options/workflows:
+Almost all features are available in both locations. The main limitation of github's Web UI is that they currently do not support upload of images.
+The table below outlines several workflows:
 
 [options="header"]
 |=========================
 | *Task* | local/offline | github.com/online 
 | *Create text file* | git add + commit + push |  Click the '+' icon, name the file and submit 
 | *Add image/binary* | git add + commit + push | N/A
-| *Edit content* | git commit + push | Click the 'Edit' button, edit and submit
-| *Delete content* | git rm + commit + push | Use the new 'Delete' button on the file. http://prose.io/ is an alternative UI that also allows deletes
+| *Edit content* | git commit + push | Click the 'Edit' button (appears as a pencil), edit the content, and submit
+| *Delete content* | git rm + commit + push | Click the 'Delete' button on the file (appears as a garbage can). http://prose.io/ is an alternative UI that also allows deletes
 | *Notifications* | N/A | click 'Watch' repository and you can control the amount of notifications you get 
 | *Comments* | N/A | use the github issue tracker to ask for clarifications or simply submit suggestions as a pull-request
 |=========================
 
-Note: *Everyone* can contribute to the documentation, JBoss Tools committers all have push access and any non-committers can 
-edit and they will be turned into pull-requests which a committer can then apply. Even if the edits are not applied directly 
-your edits are visible in your fork.
+Note: *Everyone* can contribute to the documentation, JBoss Tools committers all have push access to this repository. Any non-committers can 
+make edits, which will become pull-requests that any committer can then apply. Even if the edits are not applied directly,
+your edits will be visible in your fork.
 
 

README.adoc

@@ -1,11 +1,66 @@
-== JBoss Tools Developer Documentation
+= JBoss Tools Developer Documentation 
 
 This repository contains documentation for building and developing JBoss Tools.
 
 It is meant to replace the articles related to development at jboss.org wiki found at https://community.jboss.org/wiki/JBossTools
 
 See link:CONTRIBUTING.adoc[Contributing] for how to write/add to these docs.
 
-In general it is to be a wiki all developers can push docs to, external contributors can do pull-requests or report issues
-to get things clarified/documented better.
+This repo should be considered a wiki, into which all developers can push docs. External contributors can do pull requests or report issues to improve the quality, clarity, and breadth of this documentation.
+
+== Table of Contents
+* Getting Started
+** link:building/setup_development_environment.adoc[Setting up the eclipse development environment].
+** link:building/configuring_git_workflow.adoc[Configuring your git workflow]. 
+** link:building/target_platforms/target_platforms_for_consumers.adoc[Using target platforms in eclipse]
+* Target Platforms
+** link:building/target_platforms/target_platforms_for_consumers.adoc[Using target platforms in eclipse]
+** link:building/target_platforms/target_platforms_updates.adoc[Target platform update process]
+** link:building/target_platforms/target_platforms_releases.adoc[Target platform release process]
+** link:building/target_platforms/target_platforms_updates.adoc[Requesting Target Platform Updates]
+* Building a project (also called module or component)
+** link:building/how_to_build_jbosstools_faq.adoc[JBoss Tools Build FAQ]
+** link:building/build_from_commandline.adoc[Building from the command line]
+*** link:building/build_options.adoc[Build options & flags]
+** link:building/build_from_eclipse.adoc[Building with Eclipse (using m2e)]
+** link:source/build_source_bundles_features_and_src_zips.adoc[How to build source bundles, features, and source zips]
+** link:building/export_plugin_from_eclipse.adoc[Exporting plugins from eclipse]
+** link:building/tycho.adoc[All about Tycho]
+*** link:building/how_to_test_tycho.adoc[How to test new versions of Tycho]
+* Testing & Debugging
+** link:debugging/runtime_workbench.adoc[Debugging via Runtime Workbench]
+** link:debugging/install_a_local_build.adoc[Installing a local build]
+** link:debugging/how_to_test_a_build.adoc[Testing an installed build]
+** link:debugging/remote_debugging.adoc#Using-the-Eclipse-debugger[Debugging Surefire Tests w/ Eclipse Remote Debugger]
+* Source and Project Management
+** link:source/new_project_process.adoc[Adding a new module / repository to JBoss Tools or JBDS]
+** link:source/how_to_add_a_plugin_or_feature_to_an_existing_project.adoc[Adding a new plugin or feature to an existing JBoss Tools 4.x module]
+** link:source/how_to_add_a_test_plugin_or_feature.adoc[Adding a new unit or integration test and test feature]
+** link:building/target_platforms/target_platforms_updates.adoc[Requesting Target Platform Updates]
+** link:source/how_to_add_an_update_site.adoc[Adding an update site] or link:source/build_update_sites_using_associate_sites.adoc[associate site]
+** link:source/publishing_features_downstream.adoc[Publishing features to JBoss Tools, Red Hat JBoss Developer Studio, JBoss Central, Early Access, and Eclipse Marketplace]
+** link:source/third_party.adoc[Bundling Third Party Library Dependencies]
+** link:source/versioning.adoc[Versioning rules] 
+** link:https://developer.jboss.org/en/tools/blog/2011/09/17/coping-with-versions-in-large-multi-module-osgi-projects[Updating Versions for Components]
+* Process and Protocol
+** link:community/how_to_use_jira.adoc[How to use JIRA]
+** link:community/code_freezes.adoc[Code freezes]
+** link:community/release_guidelines.adoc[Release guidelines]
+** link:source/tagging_branching.adoc[Tagging & branching]
+* API
+** link:api/exposing_api.adoc[Exposing And Migrating API]
+** Common APIs You May Need
+*** link:api/foundation/foundation_api.adoc[Foundation - Base Classes for Every Plugin]
+*** link:api/usage/usage_api.adoc[Usage tracking]
+*** link:api/central/how-to-add-proxy-wizards.adoc[Proxy Wizards]
+* link:community/README.adoc[Community contribution and involvement]
+
+=== Other documents
+
+Many of these docs are old and need to be updated, or to be moved to better categories.
+
+* link:building/build_documentation.adoc[How to build JBoss Tools 4.x documentation]
+* link:building/build_job_cascade_and_where_to_find_build_results.adoc[Build cascade & results]
+* link:building/how_to_build_jbosstools_4.adoc[How to build JBoss Tools 4.0]
+
 

central/how-to-add-proxy-wizards.adoc renamed to api/central/how-to-add-proxy-wizards.adoc

@@ -0,0 +1,53 @@
+= Exposing API
+
+When designing a new plugin, it is very important to decide what code will be exposed for other clients to call, and what code will remain internal. If you do not do this properly when first designing your plugin, it is very likely that clients will make use of this code, and you will be forced to support it. 
+
+== Package Names
+
+All packages that are meant to hold internal code should have a segment in the package name that reads `internal`. All packages that lack this segment are assumed to be public, and open for anyone to make use of. 
+
+== Exposing your API packages
+
+In the `Runtime` tab of your `plugin.xml` editor in Eclipse, you can choose which packages to export. You should export only those packages which you intend others to use. Typically, you would export all packages that do not have .internal in the package name. You may find reason not to expose other packages, as well, but you should consider if perhaps those packages should have `internal` added to them. 
+
+== But my test cases need the internal code!
+
+The `Runtime` tab of the `plugin.xml` editor actually persists its changes in the `Manifest.mf` file. When looking at this file, you may see the following:
+
+```
+Export-Package: org.jboss.ide.eclipse.archives.core,
+ org.jboss.ide.eclipse.archives.core.model.internal,
+ org.jboss.ide.eclipse.archives.core.model.internal.xb,
+```
+
+To expose a package to only your test plugins, you can change this as follows:
+```
+Export-Package: org.jboss.ide.eclipse.archives.core,
+ org.jboss.ide.eclipse.archives.core.model.internal;x-friends:="org.jboss.ide.eclipse.archives.test",
+ org.jboss.ide.eclipse.archives.core.model.internal.xb;x-friends:="org.jboss.ide.eclipse.archives.test",
+```
+
+This will limit which downstream consumers have access to the classes and may make use of them. 
+
+== I accidentally made a package public and others are using it!
+
+In this case, you have a few tasks that need to be done. You are required to maintain the code as API for at least one major release, but you will want to discourage new consumers from using the package. You should mark the package as internal in the following way:
+
+```
+Export-Package: org.jboss.ide.eclipse.archives.core,
+ org.jboss.ide.eclipse.archives.core.asf,
+ org.jboss.ide.eclipse.archives.core.model.oopsprivate;x-internal:=true,
+```
+
+This will discourage new consumers from using this package, but will not prevent it. 
+
+At this point, you will need to discover any and all consumers who are using this package, and provide them suitable API replacement in packages that are to be exposed for consumption.
+
+After waiting for a full major release, you may be able to migrate the `oopsprivate` package into an internal one, after fully announcing your intentions to mailto:[email protected][[email protected]] and ensuring that there are no consumers who indicate an issue with the change. 
+
+
+= Evolving APIs
+
+Changing API is always something that should be done very carefully. Changes generally must be source-compatible AND binary compatible. Changing method signatures, class heirarchy, visibility of fields, all have the potential to break binary compatibility. 
+
+For more information on this topic, please consult Eclipse's guide link:https://wiki.eclipse.org/Evolving_Java-based_APIs_2[Evolving Java-based APIs] for a comprehensive list of compatibility for various changes.