Development and Deployment Best Practices

The purpose of this page is to collect development and deployment best practices in a single place.

Ticket Management:

All non-trivial productions system changes should be documented and executed using a ticketing system. You can use any ticket system you wish. Here are some popular choices:

• Github.com (preferred solution) - has good ticket and discussion tools.
• Atlassian (bitbucket+jira) - has good ticket and discussion tools.
• Google docs
  • Create a Google Doc whose name represents the next ticket number. Increment this number every time you create a new ticket.
  • Each new ticket you create will include the ticket number as the prefix.
  • The document/ticket will include your standard sections like: Summary, Details, Implementation, Acceptance Testing, etc...
  • As the development team creates release artifacts, they will create a date-stamped Release section at the bottom of the document to reference the location of the artifacts.
  • Chuck's Opinion
    • This system has worked for me for a very long time.
    • Google search is amazing.
• Trello + Google Docs
  • Note that trello is an Atlassian company
  • Trello holds the ticket summary
  • Google Doc URL is referenced by trello ticket
  • Google Doc is option - only needed if ticket is sufficently complex as to outgrow trello's description.
  • Trello has a plugin that exposes a ticket number
  • Chuck's Opinion
    • Trello is overly simple
    • Trello + Google Docs provides a nice balance of using auto-generated tickets and summary from trello with the power of google docs.
  • Atlassian and github both have tools for managing tickets. Both are viable tools.
• redmine.org - open source project management

• Below are common ticket statuses when using a kanban board.
  • TICKET DRAFT: Where we will flesh out a ticket prior to moving to YOU moving the card to QUOTE Dev for dev team to quote.
  • QUOTE DEV: You requesting a quote from DEV - Once quoted, DEV to move card to QUOTE REVIEW (DEV will not spend more than 2 hours generating a quote per email attached "Quoting Best Practices.pdf"
  • QUOTE REVIEW: DEV puts card here awaiting response from YOU, once approved, YOU moves the card to DEVELOPMENT APPROVED
  • URGENT TICKET: There are times when an urgent ticket will come that prevents the ability to quote due to time constraints. in these situations, please do not spend more than 4 hours on a ticket without requesting approval for additional time.
  • DEVELOPMENT APPROVED: If quote approved, YOU would move to this list. DEV will move the card to IN DEVELOPMENT once they begin work on the ticket.
  • IN DEVELOPMENT: Actively being worked on by DEV, once ready for testing DEV to move the card to READY FOR TEST DEPLOYMENT.
  • READY FOR TEST DEPLOYMENT: Ready for CHUBOE to release into test. Following deployment to Test, CHUBOE should move ticket to UAT
  • UAT: In test; awaiting user testing by YOU. YOU to move the card to READY FOR PROD DEPLOYMENT after testing complete. DEV to attach JAR to Card.
  • READY FOR PROD DEPLOYMENT: Staged for deployment, awaiting next deployment run. DEV to move card to DONE once deployed.
  • DONE: Deployed/Ticket complete.
  • BACKLOG/PARKING LOT: On hold, etc. If YOU wants start one of these cards up again, YOU will move it to the appropriate List.

Budget/Quote Management

Quote management is import for many reasons.

• Helps protect the budget
• Ensure time is spent on most important activities
• Give the project manager ability say no if a ticket is too costly or complicated

Below are guidelines for managing and executing quotes:

• It is assumed that the development team (DEV) will take some paid time to evaluate and formulate a quote.
• It is assumed DEV will consume between 1 or 2 billable hours and respond to a development request.
• If DEV is not able to find a quick solution, please respond with how much time you believe would be required to estimate.
• 4 hours will be the absolute most DEV should consume without prior approval of a ticket. This situation most often occurs when a ticket is as a result of a production issue. Examples include the when system is down in part or whole, or the data in the system is corrupt.
• All time entries should be against tickets.

Monthly Consumption of Time

It is assumed that development teams will send either bi-weekly or monthly (preferred) invoices. In the early stages of a project, the development team may even send weekly invoices until trust and best practices are demonstrated by all parties.

Weekly or bi-weekly time sheet consumption updates should discussed.

Table and Column Creation and Modification

• All new tables should be prefixed with either the customer or developer prefix. Examples include Chuboe_SomeTable or Logi_SomeTable.
• When modifying a core table, all added columns should always include your prefix. Example include Chuboe_SomeField or Logi_SomeTable. This is true even if the column you are adding is a core column present on another table. The reason for this change is to prevent migration/upgrade collisions if someone adds the same column in a later release.
• Postgresql stores all tables and columns (all DDL) in lowercase.
• iDempiere (Tables and Columns) should always be changed to match the following case: Prefix_SomeTable_Name. This concept is important because iDempiere generates code from Table and Column values. This convention closely follows java case standard.
• Boolean columns
  • Mandatory = Y (most always be mandatory with a default value)
• ColumnSQL
  • Always use a prefix when referencing a column in sql. Example c_order.documentno

Code Repository

All code will be maintained in a source code repository. Github is the default source code control repository. Time and care will be given for:

• Ensure both all necessary parties have access to the source code repository at all times.
• The code repository should always be available (100% uptime). This is a moot point for Github.
• The code repository should be backed up regularly. This is a moot point for Github.

Most plugin code can be written in a single 'default' branch. There are times when a long-running and disruptive change is under development. If you have such a ticket/change, please create this change in a different branch so that it is not accidentally released to production as part of a different ticket. Branching concepts are an advanced topic. Care should be given when developing non-trivial plugins.

A single repository is used to keep all customer plugins. The root directory of the repo is a collection of directories bearing plugins names. Example:

• com.logilite.order.model
• com.logilite.order.process.createproduction
• com.logilite.invoice.process.print
• etc...

There are times when a customer uses a plugin from another source (including community, another repo from another customer, etc...). Any time you add a plugin to your deployment, you need to include the plugin director name in your code repository. At a minimum, this directory should contain a readme with details about the plugin (who, what, when where, etc...). This is important when migrating from one major version to another where you re-deploy all plugins. It is uncomfortable to realize you have no idea where a plugin came from, and you cannot find the source.

Deployment Repository

Any changes planned for production should be committed to a deployment repository. Changes include:

• Plugins
• Packins
• SQL scripts
• Digital certificates
• Changes to file contents or structures
• Etc...

The deployment repository includes:

• Ticket deployment template script
• Release deployment template script
• Open tickets (each ticket is a folder bearing the ticket number)
• Closed tickets - directory of all closed tickets. Note that ticket directory names are change to include a date stamp due to the fact that a ticket can be release multiple times.

References for Deployment

• Automated scripted release management
• New table model development

Release Management

Releases are tickets themselves. Their purpose is to orchestrate the rapid and scripted release of tickets.

iDempiere Resources

Plugin Development

We adopt the concept of single-purpose plugins - a component of SOLID object oriented programming. Doing so helps all members of the development and support team understand development artifacts.

• plugin naming convention
  • Note: the concept of a plugin name is different than the java package name. There is no requirement that the plugin and package names are the same; however, you do want them to be as similar as possible.
  • definition: url.topic.type.qualifier
  • It is ok to use short names (bp vs businesspartner) - just be consistent
  • examples
    • com.chuboe.order.event.setpaymentrule
    • com.chuboe.bp.event.createloc
    • com.logilite.bp.callout.setdefaults
    • com.yourco.bp.model.main
  • Try not have have overlapping names where one is a subset of another
    • Example of what not to do:
      • com.chuboe.bp.process
      • com.chuboe.bp.process.getorders
    • If you find yourself in this situation of creating a single plugin of its name, use the .main suffix.
      • com.yourco.bp.model.main
• Model Events vs IModelFactory
  • For core tables, use ModelEvents instead of IModelFactory
    • You should have a very compelling reason to create a IModelFactory for a core table.
  • For custom tables, get in the habit of always creating models for your tables.
• Processes
  • Transaction management
    • Be careful of long-running, uncommited transactions. Unless you have strong rollback requirements, incremental commits are preferred to minimize overhead.

iDempiere Core Changes

You should go to great lengths to prevent changes to the core. If you believe there is a need to change the core, you should discuss the need with the core development team first. If they agree, they will help guide you through the process of finding the best solution for both you and the core. The project has a goal that no one ever needs to modify the core.

Should you find yourself needing to modify the core, there are topics in the ERP Academy to help you support these changes.