Author: jleroux
Date: Tue Oct 10 23:16:03 2006
New Revision: 462704
URL: http://svn.apache.org/viewvc?view=rev&rev=462704
Log:
A patch from Jacopo : "Best Practices Guide migrated to the Documentation site
(Confluence)" (http://issues.apache.org/jira/browse/OFBIZ-373)
Modified:
incubator/ofbiz/site/best-practices.html
incubator/ofbiz/site/documents.html
Modified: incubator/ofbiz/site/best-practices.html
URL:
http://svn.apache.org/viewvc/incubator/ofbiz/site/best-practices.html?view=diff&rev=462704&r1=462703&r2=462704
==============================================================================
--- incubator/ofbiz/site/best-practices.html (original)
+++ incubator/ofbiz/site/best-practices.html Tue Oct 10 23:16:03 2006
@@ -1,601 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>
-<!--
-
-Copyright 2001-2006 The Apache Software Foundation
-
-Licensed 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.
--->
-<html xmlns="http://www.w3.org/1999/xhtml";>
-
- <head>
- <title>The Open For Business Project - Best Practices Guide</title>
- <link rel="stylesheet" href="images/ofbws.css" type="text/css"/>
- <meta name="keywords" content="Open Source ERP,Open Source CRM,Open Source
E-Commerce,Open Source eCommerce,Open Source POS,Open Source SCM,Open Source
MRP,Open Source CMMS,Open Source EAM,web
services,workflow,ebusiness,e-business,ecommerce,e-commerce,automation,enterprise
software,open source,entity engine,service
engine,erp,crm,party,accounting,facility,supply,chain,management,catalog,order,project,task,work
effort,financial,ledger,content management,customer,inventory"/>
- <link rel="shortcut icon" href="images/ofbiz.ico"/>
-</head>
-<body>
-
-<!-- start header -->
-<div class="headerboxoutside">
- <div class="headerboxtop">
- <div class="left">
- <a href="http://incubator.apache.org/ofbiz/";><img
src="images/ofbiz_logo.jpg" border="0" alt="The Open For Business Project"/></a>
- </div>
- <div class="right">
- <a href="http://incubator.apache.org/projects/ofbiz.html";><img
class="tag-button"
src="http://incubator.apache.org/images/apache-incubator-logo.png"; alt="Apache
Incubator"/></a>
-
- <a href="http://incubator.apache.org/ofbiz/";><img
class="tag-button" src="images/ofbiz_powered.gif" alt="Powered By Apache
OFBiz"/></a>
- </div>
- <div class="endcolumns"><span> </span></div>
- </div>
-</div>
-<!-- end header -->
-
-<div class="centerarea contentarea">
-
-<center><h2>The Open For Business Project - Best Practices Guide</h2></center>
-
-<div class='contenttext'>Written By: David E. Jones, <a href="mailto:[EMAIL
PROTECTED]">[EMAIL PROTECTED]</a></div>
-<div class='contenttext'>Last Updated: 12 June 2003</div>
-
-<p class='contenttext'><b><u><a name="TOC">Table of Contents</a></u></b></p>
-
-<ul>
- <li class='contenttext'><a href="#Introduction">Introduction</a></li>
- <li class='contenttext'><a href="#General">General Concepts</a></li>
- <li class='contenttext'><a href="#Data">Data Layer</a></li>
- <li class='contenttext'><a href="#Logic">Logic Layer</a></li>
- <li class='contenttext'><a href="#Presentation">Presentation Layer</a></li>
- <li class='contenttext'><a href="#Before">Before Starting - Methodology
Recommendations</a></li>
- <li class='contenttext'><a href="#Differences">Managing Your Source
Differences</a></li>
-</ul>
-
-<p class='contenttext'><b><u><a
name="Introduction">Introduction</a></u></b></p>
-
-<p class='contenttext'>This documents presents best-practices for development
-and architecture related to The Open For Business Project.</p>
-
-<p class='contenttext'>It will not try to
-cover all of the practically limitless options available for using
-tools in OFBiz and the many related open source projects and standard APIs.
-It will also not try to cover all development best-practices, just the ones
-most closely related to creating and modifying OFBiz based components.</p>
-
-<p class='contenttext'>It will try to cover the best practices for every
-layer of architecture and the best tools to use, and for steps that should
-be taken prior to even laying out what code should be written. In some
-cases there will be close seconds to the best practices that will be
-presented because in some cases these second-best-practices will be more
-appropriate.</p>
-
-<p class='contenttext'>Note that this document assumes some knowledge of the
-OFBiz Core Framework. With some basic knowledge it can answer a lot of
questions
-about how certain things should be used. If you are not familiar with the
-OFBiz Core Framework this will give you an introduction to it, but some things
-may not make a lot of sense to you.</p>
-
-<!-- second bests:
- - view layer: JSP and regions instead of JPublish and FreeMarker
--->
-
-<p class='contenttext'><b><u><a name="General">General Concepts</a></u></b></p>
-
-<p class='contenttext'><b><a name="ReduceCode">Redice Code Redundancy &
Size</a></b></p>
-
-<p class='contenttext'>There are various techniques that can be applied to
this problem
-that produce good results. The most common, but least effective, practice is
code
-generation. Because it is not something that I consider to be a best practice,
I won't
-discuss it further here.</p>
-
-<p class='contenttext'>The best practices that are used in various places in
the OFBiz
-framework are dynamic APIs such as the Entity and Service Engines, and special
purpose
-languages like the Workflow and Rule Engines and the MiniLang library.</p>
-
-<p class='contenttext'>The dynamic API pattern is characterized by a generic
API with
-simple operations that behave differently based on configuration and domain
definition
-files. These are usually XML files. This is an alternative to code generation
and the
-input or domain description files used for generating code can often be used
unchanged
-to drive a dynamic API resulting in much less code and much more dynamic,
ad-hoc control.</p>
-
-<p class='contenttext'>A special purpose language is used to create logic
-in a language or using a tool that fits the specific need more appropriately
-than a general purpose procedural language like Java. This reduces code
because it is
-easier to describe what you want in a context that closely matches the problem
that
-needs to be solved than it is to use a generic language. High level conepts
can be
-expressed without the need to write a lot of code.</p>
-
-<p class='contenttext'><b><u><a name="Data">Data Layer</a></u></b></p>
-
-<p class='contenttext'>The best-practice tool to use in the data layer is the
OFBiz
-Entity Engine. For most applications the Entity Engine will elegantly do the
work
-for 99% of your database interaction needs. In the few cases where the Entity
Engine
-is not sufficient I recommend using custom JDBC code for your queries or other
-commands. That would be one of the second-best-practices that are sometimes
needed.</p>
-
-<p class='contenttext'>When using the Entity Engine refer to entity and field
names
-using inline strings. This makes it much easier to read and maintain your
code. If you
-need to prepare a large Map or EntityCondition to pass to an EE method it is
generally
-cleaner to do it on a separate line, or on various separate lines before the
actual
-EE method call.</p>
-
-<p class='contenttext'>Use a simple, normalized data model based on the needs
of your
-applications. Usually the data model can be driven directly by the
requirements for
-the functionality that will use the entities. This usually results in a highly
-normalized data model which will make your life much easier. When you need
combined
-data for reporting, use the view-entity feature to accomplish joins and
grouping and
-summarizing data.</p>
-
-<p class='contenttext'>Always use primary keys and avoid the use of generic
sequenced
-primary keys when a more descriptive composite key is possible. Always use
relationship
-definitions to document how entities are used together, to make it easier to
get at
-related data, to constrain field by foreign keys, and to improve performance
through
-automatic foreign key based indexes.</p>
-
-<p class='contenttext'><b><u><a name="Logic">Logic Layer</a></u></b></p>
-
-<p class='contenttext'>The best tool to use for invoking logic is the OFBiz
Service
-Engine. Nearly all business logic should be implemented as a service to
improve
-reusability and facilitate component based development.</p>
-
-<p class='contenttext'>Even though services are very flexible there are cases
where
-the service model is not appropriate, even for business logic. In some cases
calling
-a script or Java method directly is necessary and in those cases using the
service
-model would not make sense and should not be used.</p>
-
-<p class='contenttext'>The Service Engine reduces code size by providing many
ways
-to use logic implemented as a service. You can call your logic synchronously,
-asynchronously or on a schedule. When you are calling a service you don't need
to
-know where it is located or how it is implemented. This makes it easy to
effectively
-leverage remote services and services written using different languages. Being
able
-to transparently call logic in different languages through the Service Engine
is
-important for the effective use of special purpose languages.</p>
-
-<p class='contenttext'>When defining your services try to keep them as simple
as
-possible using interface services or other techniques. Whenever a service is
based
-on an entity be sure to use the auto-attributes tag to create attributes from
the
-entity field definitions. Also, rather than redefining attributes using the
-attribute tag, use the override tag and only specify the information you want
-to change.</p>
-
-<p class='contenttext'>Always implement your service using the easiest and
most appropriate
-language or tool. You can implement services with many different languages
-including Java, BeanShell or any BSF compliant scripting language (Jython,
Jacl,
-JavaScript, etc), OFBiz Workflow Engine processes, OFBiz MiniLang
simple-methods,
-and various others. Additional languages can be supported by writing simple
-adapters.</p>
-
-<p class='contenttext'>Always call remote logic through the Service Engine.
-You can call remote services through various mechanisms
-including HTTP, SOAP, JMS, and others. You can also add remote service
invocation
-mechanisms by creating a simple adapter.</p>
-
-<p class='contenttext'>Most of the time you will want to let the Service Engine
-automatically wrap your service call in a transaciton so that the whole thing
-will succeed, or the whole thing will fail. Note that if you call a service
inside
-an existing transaction it will recognize the current transaction and use it
-instead of trying to create another one.</p>
-
-<p class='contenttext'><b><u><a name="Presentation">Presentation
Layer</a></u></b></p>
-
-<p class='contenttext'>Always separate input processing logic, view data
preparation
-logic, and view presentation templates. This will make it easy to reuse logic
not
-only in web applications, but also for independent fat client applications. It
will
-also make it easier to organize your code and find a specific piece of
functionality
-when debugging or exploring to find out how a component works.</p>
-
-<p class='contenttext'>For each of the three separate pieces there are special
-best-practices tools to use.</p>
-
-<p class='contenttext'><b><a name="InputProcessing">Input Processing
Logic</a></b></p>
-
-<p class='contenttext'>Input processing logic should always be associated
-with a request in the controller.xml file and never with a view. Input
processing
-logic should generally be implemented as a service and called through the
service
-event handler which will automatically pull data from request parameters or
-attributes and convert it from a string to the object type defined in the
service
-definition. This makes it easy to specify which parameters you care about
-processing just using the service definition, and let the framework get them
-ready for you.</p>
-
-<p class='contenttext'>There are various cases where input processing logic
-cannot be implemented as a service. There are various other types of event
-handlers for logic associated with requests that give you more to the
-request context and are not environment agnostic like services are. One
example
-is receiving uploaded data. Another good example is doing special
pre-processing
-and validation on parameters before passing them to a service for processing.
-Note that you can always call services from these custom events and wherever
-possible generic logic should be implemented in services.</p>
-
-<p class='contenttext'>Always let the Control Servlet configuration handle
decisions
-about the appropriate response to take for a request given the result string
from
-an event. In most cases the response will be the generation of a view, but
sometimes
-it will make sense to chain requests together to acheive logic reuse or more
-advanced flow control.</p>
-
-<p class='contenttext'><b><a name="ViewDataPreparation">View Data Preparation
Logic</a></b></p>
-
-<p class='contenttext'>View data preparation logic should always be associated
-with the view template it is meant to prepare data for. This should be done
-through the OFBiz Screen Widget in the screen definition XML file by
specifying a script action. When
-a screen is split up into multiple templates or screens the data preparation
action should be
-associated only with the individual small screen that it prepares data for.
-This makes it easier to move templates and content pieces around and reuse them
-in many places.</p>
-
-<p class='contenttext'>View data preparation logic should be specified as
actions
-in the XML screen definition or if necessary implemented in a
-dynamic scripting language such as JavaScript, BeanShell, Jython or Jacl to
make
-it easy to modify the user interface on the fly. Generic data retreival should
-be implemented as services which should be called from these dynamic action
-scripts. This makes it easier to share and reuse this functionality in multiple
-pages and in other types of user interfaces.</p>
-
-<p class='contenttext'>When preparing data in view actions you should make the
-data available to the view template by putting it in the "context" object. All
-attributes in the context object will be made avilable in the context of the
-template, if the template languge supports that.</p>
-
-<p class='contenttext'>Note that when using JSP for a view template you cannot
-use JPublish so the actions facility will not be available. Our recommendation
-for JSPs is to have a single scriplet at the top of the page that prepares the
-data. In this case try to call worker services or worker Java methods to do
-most of the work and to keep as much logic as possible out of the page.</p>
-
-<p class='contenttext'><b><a name="ViewPresentation">View Presentation
Templates</a></b></p>
-
-<p class='contenttext'>The best-practice template engine that we recommend for
-HTML and other text generation is FreeMarker.
-It is like Velocity from Jakarta, but much more flexible and fits in
-nicely with other OFBiz Core Framework tools. Rather than running FreeMarker
-templates directly we strongly recommend using the OFBiz Screen Widget so that
actions can be
-associated with screens and they can be decorated with common
-templates. We'll describe how to best use this below.</p>
-
-<p class='contenttext'>The view presenation templates should always be kept as
-simple as possible and common content such as headers, footers, sidebars, and
so
-on should be added at run-time using the decoration pattern. The template file
-that should be used to decorate each page is specified in the screen
-definition XML file.</p>
-
-<p class='contenttext'>Always use the view generation tool that most closely
-matches your needs. FreeMarker is the recommended tool for generating text
-output, but there are many situations where other tools are more appropriate.
-If you want to use other text generation tools such
-as Velocity or XSLT we recommend you do so through the Screen Widget,
especially if
-you want it to be decorated and have actions run to prepare for the
templates.</p>
-
-<p class='contenttext'>When you want to display report like views we recommend
using
-the Screen Widget along with FreeMarker to generate an XSL:FO XML file, and
use the
-Screen Widget FOP view handler in the Control Servlet configuration to
transform
-it into a PDF to send to the client. This approach allows you to use the same
tools
-for these reports as with other views in your applications and offers
essentially
-unlimited flexibility. As an alternative you can use other more traditional
reporting tools such as
-Jasper Reports or DataVision and mounting those reports through a view-map in
the
-Control Servlet configuration file (controller.xml).</p>
-
-<p class='contenttext'>If you have UI patterns that are repeated frequently
-such as forms, query data displays, tab or menu bars, expanding tree views, and
-so forth we currently recommend using an XML file to describe the UI pattern
-and then transform it to HTML or other output using a rendering engine for that
-specific XML format, or using XSLT/FreeMarker/etc to transform it into the
-desired output.</p>
-
-<p class='contenttext'>For most forms the best way to represent them is to use
-the OFBiz Form Widget which accepts a generic form definition in XML that is
-usable with multiple user interface types, and that takes advantage of existing
-assets in your OFBiz based code such as Service and Entity definitions. This
-results in code that is much smaller and easier to maintain.</p>
-
-<p class='contenttext'>When using FreeMarker is not possible or practical we
-recommend using another dynamic templating language such as Velocity. When
-that is also not possible or practical we recommend using JSPs. But, note that
-when using JSPs you cannot take advantage of the actions or decoration
-templates because you cannot run it through JPublish. This is thanks to
-limitations in the JSP specification. Even through you cannot use the decorator
-patter, you can use the composite view pattern with the OFBiz Regions
-framework. Regions are specified in the regions.xml file. Note that these are
-not as easy to use as Screen Widget composite views, and they do not support
-actions. But the Regions framework does offer a lot of flexibility and is
-very useful in many cases.</p>
-
-
-<!-- ================================================================ -->
-<hr class='sepbar'>
-
-<p class='contenttext'><b><u><a name="Before">Before Starting - Methodology
Recommendations</a></u></b></p>
-
-<p class='contenttext'>Before you can build something that something has to be
-defined. Every detail has to be decided at some point. Because of the
difficulty
-of communication between individuals and the difficulties that are inherently
-involved in complex systems we recommend various practices.</p>
-
-<p class='contenttext'>While these techniques are used for some components in
-the core Open For Business functionality they are primarily meant for those
-who are creating derivative works based on OFBiz. The reason for this is that
-OFBiz is a generic framework, set of application components and suite of
-applications. In many cases these applications can be used as is but they are
not
-meant to be everything to everyone. Because of this work will likely be needed
-for derivative works that are targeted at a specific industry, type of
business,
-or specific end user.</p>
-
-<p class='contenttext'><b><a name="Methodology">Methodology: Keep it simple,
but not too simple</a></b></p>
-
-<p class='contenttext'>There are dozens of different software development
-methodologies, and more are being introducted all the time. There are lots of
-good ideas presented in the hundreds, or even thousands, of documents
-available about different methodologies. In general we recommend the "agile"
-approach, but that needs to be qualified given the different perspectives
-that have been attached to that name. In general we recommend keeping it as
-simple as possible, but not too simple. For more specifics on agile software
-development see the <a href="http://www.agilealliance.org";>Agile Alliance web
site</a>.</p>
-
-<p class='contenttext'>So the big question is generally: what is the minimum
-that we need to handle this project? The more methodology you have the more
-time and money you will spend on it. The less methodology you have the greater
-the chance that the requirements of the project will not be satisfied.</p>
-
-<p class='contenttext'><b><a name="Roles">Minimal Roles</a></b></p>
-
-<p class='contenttext'>There are really only two roles necessary for any
project:
-a buyer and a seller. In the case of software projects, and other service
offerings,
-the more common terms are customer and developer. Those are the terms that
will be used
-in this document. The term developer is used loosely here and refers to anyone
that
-produces actual deliverables. The term customer is also used loosely here and
refers
-to anyone that specifies what will be done and pays for it to be done. In some
cases
-the customer and developer will be the same person, or the same group of
people.</p>
-
-<p class='contenttext'>It should be noted here that an important part of the
-"customer" role is the actual target user(s) of the software. If possible
reviewing
-stories and use cases (as described below) with users should be done.
Interviewing
-those who are currently performing tasks that will in the future involve
interaction
-with the new system can make it much easier to acheive complete and effective
results.
-This is true on many levels. For instance, the best usability can be acheived
by
-reviewing screen/page prototypes with real users and then validating final
deliverables
-with real users. If the user group is large this may require a lot of work to
get
-a good sampling of the different users of the system.</p>
-
-<p class='contenttext'>In many projects the two roles, customer and developer,
will
-consist of groups of people and other roles will be introduced within the
groups
-to clarify responsibilities. In these cases the methodology may also have to be
-more significant to keep things from deteriorating into chaos.</p>
-
-<p class='contenttext'>One practice that can
-reduce the need for a complicated and detailed methodology is to have one
person from
-each group act as the agent for the entire group. Of course, that agent should
discuss
-things with the rest of the group, but if the number of voices for interaction
between
-the groups can be consolidated to one then communication and management of
details will
-be much easier.</p>
-
-<p class='contenttext'>Note that for large projects having one agent for each
side will
-not be practical. In those cases dividing the scope of the project and
likewise dividing
-the customer and developer groups will be necessary.</p>
-
-<p class='contenttext'>Another variation on this is where a group creates a
product
-targeted at hundreds or thousands of customers. In this case the "customer"
that
-defines the product will be part of the same organization that produces the
product.
-Given the definition of customer above the sales, marketing, and testing
groups should
-be in the customer group, and an agent from that combined group should
coordinate with
-the development group.</p>
-
-<p class='contenttext'><b><a name="Communication">Minimal
Communication</a></b></p>
-
-<p class='contenttext'>The biggest trick with communication is to find the
balance
-between to much and too little communication. The burden for this is generally
on the
-customer because it is customer that specifies what will be build. Like I said
at the
-beginning of this section everything that will be built MUST be defined sooner
or
-later. Anything that is not specified by the customer can be handled in one of
two
-ways. The developer can decide what will fit into the gaps or the developer
can request
-clarification and details from the customer.</p>
-
-<p class='contenttext'>To facilitate communication and make sure that the
final result
-satisfies the needs requested by the customer the following process is
recommended.</p>
-
-<p class='contenttext'><b><a name="Process">Minimal Process</a></b></p>
-
-<p class='contenttext'>One important aspect of this process is that it should
be
-repeated frequently and the scope for each pass should be kept small so that
when
-miscommunications occur they can be identified and resolved quickly.</p>
-
-<p class='contenttext'>While this process is simple and involves simple roles
and
-artifacts it can be used as a skeleton for a much larger and more detailed
process.
-Each step can be divided into many steps and extra steps to compensate for the
-needs of a specific project can be added.</p>
-
-<p class='contenttext'>Also note that this general process is the basis of the
Work
-Effort components that are part of OFBiz and those tools, as well as many
other
-available tools, can be used to make artifacts and other information easier to
manage.</p>
-
-<ol>
- <li class='contenttext'>The customer requests features by telling a "story"
about each feature desired.
- <li class='contenttext'>The developer creates one or more requirements for
each story by writing a more formal "use case" describing in detail how the
resulting component(s) will be used.
- <li class='contenttext'>The customer reviews the use case(s) and provides
feedback to the developer if necessary. If feedback is returned the developer
adjusts the use case(s) and resubmits them to the customer. When the customer
is satisfied the requirement is approved for implementation.
- <li class='contenttext'>The developer defines tasks that must be done to
create or modify components in order to satisfy the approved requirements. At
this point, if desired, time and/or cost estimates should be associated with
the tasks.
- <li class='contenttext'>The customer can specify priorities on the request,
requirement or task level. Given that tasks may have dependencies the actual
order may be changed by the developer such that prerequisites are satisfied
first.
- <li class='contenttext'>The developer does the work described in each and
demonstrates the result to the customer. To improve developer productivity
interruptions during this time should be minimized, except of course
interruptions related to changes in what is to be done for that component. The
actual time and/or cost should be recorded at this point if desired.
- <li class='contenttext'>The customer reviews the deliverable and either
approves the work or requests adjustments as needed in the story, use case,
and/or tasks. Making adjustments at this point involves going back to previous
steps and then the same subsequent steps should be followed to complete the
process.
-</ol>
-
-<p class='contenttext'>You will notice that this process involves a great deal
of customer
-interaction. If done right the customer and developer will interact on nearly
a daily basis.
-For coordination and management periodic meetings should be held to review new
requests or
-changes to existing requests and to adjust priorities as necessary. These
meeting should be
-held once every one or two weeks for most projects.</p>
-
-<p class='contenttext'>After looking at this list you may have questions about
what
-constitutes a story, use case, and task.</p>
-
-<p class='contenttext'>A story is essentially an informal free form
-document from the customer that describes what is desired in complete
sentences or as
-an outline. Precise details are not needed at this stage. Note that this
document may
-change to be more precise or to include additional aspects. This document will
be used
-to create more formal use case(s).</p>
-
-<p class='contenttext'>A use case is a document that contains detailed
information in
-a more formal structure and represents the complete specification
corresponding to one
-or more stories. A use case should include the following:</p>
-
-<ul>
- <li class='contenttext'>The primary and other actors, defined by the roles
of the the users or systems that will be interacting with the functionality
- <li class='contenttext'>The goal(s) of each actor and/or the overall
interaction
- <li class='contenttext'>Usage scenario(s)
- <ul>
- <li class='contenttext'>The primary actor
- <li class='contenttext'>The goal of the scenario
- <li class='contenttext'>Conditions that trigger the scenario
- <li class='contenttext'>The result(s), includes both success and failure
results
- <li class='contenttext'>Scenario variations
- <li class='contenttext'>Errors, exceptions, and resulting actions
- </ul>
-</ul>
-
-<p class='contenttext'>Note that for simplicity scenarios should be kept small
and
-include only the minimal basic process. Variations on process should be
defined
-separately. Exceptions and errors in the process should be defined separately
along
-with their results.</p>
-
-<p class='contenttext'>Defining tasks is generally fairly simple and should be
done
-by the developer in a form and using terms that the developer will understand.
There
-is a lot of meta-data that is generally associated with such a task. Examples
include
-esimated and actual time and cost, start and end dates, all parties performing
or
-otherwise involved with the task, and so on.</p>
-
-<p class='contenttext'><b><a name="Before_Conclusion">Conclusion</a></b></p>
-
-<p class='contenttext'>Some basic preparations should always be done before
getting
-into the implementation. Some basic principles and a basic process
-has been presented. Because of the nature of how most projects work all of the
steps
-in the process will be done in one way or another. Following this process does
not
-require the creation of any written documents, although in many cases that will
-help quite a lot. It can be done through verbal conversation, or even a series
of
-thoughts inside one's head.</p>
-
-<p class='contenttext'>The process described is meant to be customized to your
-needs. Following it as is should do for most medium sized projects. When there
is only
-one or two individuals involved, or tens or hundreds of individuals, changes
will
-obviously be desired. When modifying the process keep in mind the basic
principles
-presented and be especially careful about leaving out communication steps,
espcially
-the communication verification steps.</p>
-
-<!-- ================================================================ -->
-<hr class='sepbar'>
-
-<p class='contenttext'><b><u><a name="Differences">Managing Your Source
Differences</a></u></b></p>
-
-<p class='contenttext'>When customizing OFBiz components for your
-specific business requirements you will most likely come across situations
where
-small changes to files are needed and it doesn't make sense to replace a
-component completely or attach logic to it through Service ECA rules or other
-means. So, how should you manage the differences between your code and the
OFBiz
-baseline code so that updating from the OFBiz baseline will be as painless as
-possible?</p>
-
-<p class='contenttext'>The first thing you should always do is isolate your
-chagnes and comment them so that it is easy to distringuish what you changed
-from the OFBiz baseline code. The final goal is to make it easy to merge your
-changes with future changes in the OFBiz baseline.</p>
-
-<p class='contenttext'>There are various ways to structure your internal
-CVS or other code repository. One very flexible, but laborious, way is to
create
-a complete copy of the OFBiz CVS tree in a module in your own CVS repository.
-This could perhaps be called "ofbizbase".
-This should contain the revisions of the code that you are currently working
with
-and allows you to selectively incorporate specific changes from the OFBiz
baseline.
-These files should be direct copies from a revision in the OFBiz CVS
repository.
-If you make changes in this module that are not part from the OFBiz baseline
they
-should be temporary changes that are meant to be overwritten and replaced with
-future versions from the OFBiz baseline.</p>
-
-<p class='contenttext'>Once your ofbizbase snapshot module as described above
is
-in place you should create another module, maybe called "ofbizdiff". This will
-contain ONLY the files that you have changed relative to your ofbizbase module.
-When updating the version of a file in your ofbizbase repository from the
-OFBiz baseline you should do a three way diff/merge to make sure the
-changes in the OFBiz baseline make it into the version of the file in your
ofbizdiff
-module as well as the file in your ofbizbase module.</p>
-
-<p class='contenttext'>The three way diff/merge will be
-done with the following three files: the old file from your ofbizbase module as
-the base, your changed file in your ofbizdiff module as the merge target, and
-the new file from the OFBiz baseline as the merge source.</p>
-
-<p class='contenttext'>The build process for this sort of a structure is very
-simple. Create a temporary build directory. Copy the entire ofbizbase tree
into
-the directory. Copy the entire ofbizdiff tree into that directory, replacing
-files as needed. In the root of the temporary build directory run the Ant build
-file. What could be more simple?</p>
-
-<p class='contenttext'>When editing files in your ofbizdiff module you should
-ALWAYS edit them in place in the ofbizdiff directory tree and copy them to the
-temporary build directory for testing. Doing this you will always be able to do
-a CVS update to see which files you have modified as you are working.</p>
-
-<p class='contenttext'>Many variations on this technique can be effectively
-used. If you don't plan to make temporary changes to ofbizbase files or update
-individual ofbizbase files selectively, you may do just fine with an archive
-(like a zip or tar.gz file) instead of a CVS module for your ofbizbase tree.
You
-could keep the current version of this archive in your ofbizdiff CVS
module.</p>
-
-<p class='contenttext'>We have heard a lot of questions about using simple
merge
-scripts to apply differences to source in the ofbizdiff tree so that full files
-do not have to be stored ant maintained there. This is fine, but it is a LOT
-harder to perform the diff/merge or other code synchronization when you don't
-have the complete files to do a three way diff/merge. So, we don't recommend
-using minimal diff files that can be applied as part of preparation for the
-build process. Just copy the file from ofbizbase to ofbizdiff and make the
-changes you need as recommended above.</p>
-
-<p class='contenttext'><b><u>For Those Comfortable with CVS
Branching/Merging</u></b></p>
-<p class='contenttext'>If you are comfortable with the branching and merging
-features in CVS you can use those very effectively to easily maintain you
-differences from the OFBiz base source tree, and still keep up-to-date with
-the latest from OFBiz without too much trouble. CVS does three-way diff/merge
-operations all the time when doing updates, and this same feature can be used
-to do the three-way diff/merge described above, but in an automatic way that
-only requires your involvement for merge collisions.</p>
-
-<p class='contenttext'>To get started do a fresh checkout from the OFBiz CVS
-repository, then remove all CVS directories
-and import the tree into a new module in your local CVS repository. Tag this
-set of files with a name like OFBIZ_20030612 (adjust for the current date)
-using a command like "cvs tag -b OFBIZ_20030612". Now just change/add things
-as you please. Note that you are not working on that branch, you are working
-on the HEAD branch unless you do something like "cvs update
-rOFBIZ_20030612".</p>
-
-<p class='contenttext'>So, now you have a bona-fide branch of OFBiz with your
-own code mixed in, but there are a ton of cool new things in the latest OFBiz
-base code that you would LOVE to have. What do you do? The easiest way to do
-this is to use the "cvs import" command, and you can do this multiple times
-to get a new vendor branch for the latest OFBiz code. For example, checkout
-the latest OFBiz code (with an export or a checkout) and from the root
-directory of that import run something like <code>'cvs import myofbiz
OFBIZ_BASE REL_3_0_0 -m "More cool stuff from OFBiz"'</code>,
-where myofbiz is the name of your local CVS repository module, and OFBIZ_BASE
-string you use to identify this vendor branch, and REL_3_0_0 is a string you
-use to identify the current set of code from OFBiz. This could also be date
-based if it isn't from an official OFBiz release or tag.</p>
-
-<p class='contenttext'>Go back to the place on your machine where you have
-HEAD checked out and merge the branch you just created with the HEAD, or the
-current set of files you have checked out. To do this run something like
-"cvs update -dP -j[the-ofbiz-tag]".</p>
-
-<p class='contenttext'>At any time to get a list of all files changed from the
base, get
-a list of all tags on the module and compare the HEAD revisions with the
-revisions tagged using the most recent OFBiz tag.</p>
-
-<hr class='sepbar'>
-<p class='contenttext'>For information about Open For Business contact David
E. Jones at <a href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</a>
-or Andy Zeneski at <a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>.</p>
-
-</div>
- </body>
-</html>
Modified: incubator/ofbiz/site/documents.html
URL:
http://svn.apache.org/viewvc/incubator/ofbiz/site/documents.html?view=diff&rev=462704&r1=462703&r2=462704
==============================================================================
--- incubator/ofbiz/site/documents.html (original)
+++ incubator/ofbiz/site/documents.html Tue Oct 10 23:16:03 2006
@@ -168,7 +168,7 @@
<div class="contenttext"><b><u>Best Practices</u></b></div>
<ul>
- <li class="contenttext"><a href="best-practices.html">Best Practices
Guide</a></li>
+ <li class="contenttext"><a
href="http://docs.ofbiz.org/display/OFBADMIN/Best+Practices+Guide";>Best
Practices Guide</a></li>
</ul>
<!-- okay, too many complaints about this being out of date now, at least
making it harder to find...
![http://incubator.apache.org/images/apache-incubator-logo.png"](http://incubator.apache.org/images/apache-incubator-logo.png"){kind=link}