diff --git a/src/.vuepress/public/assets/img/community/developers-guide/Add_Project.jpg b/src/.vuepress/public/assets/img/community/developers-guide/Add_Project.jpg new file mode 100644 index 00000000000..b699851fb73 Binary files /dev/null and b/src/.vuepress/public/assets/img/community/developers-guide/Add_Project.jpg differ diff --git a/src/.vuepress/public/assets/img/community/developers-guide/Define_a_New_Server.jpg b/src/.vuepress/public/assets/img/community/developers-guide/Define_a_New_Server.jpg new file mode 100644 index 00000000000..72019081296 Binary files /dev/null and b/src/.vuepress/public/assets/img/community/developers-guide/Define_a_New_Server.jpg differ diff --git a/src/.vuepress/public/assets/img/community/developers-guide/Installed_Runtimes.jpg b/src/.vuepress/public/assets/img/community/developers-guide/Installed_Runtimes.jpg new file mode 100644 index 00000000000..4bc2c779942 Binary files /dev/null and b/src/.vuepress/public/assets/img/community/developers-guide/Installed_Runtimes.jpg differ diff --git a/src/.vuepress/public/assets/img/community/developers-guide/New_Server.jpg b/src/.vuepress/public/assets/img/community/developers-guide/New_Server.jpg new file mode 100644 index 00000000000..49af7387529 Binary files /dev/null and b/src/.vuepress/public/assets/img/community/developers-guide/New_Server.jpg differ diff --git a/src/.vuepress/public/assets/img/community/developers-guide/Project_Facets.jpg b/src/.vuepress/public/assets/img/community/developers-guide/Project_Facets.jpg new file mode 100644 index 00000000000..a809efbc0a7 Binary files /dev/null and b/src/.vuepress/public/assets/img/community/developers-guide/Project_Facets.jpg differ diff --git a/src/.vuepress/public/assets/img/community/developers-guide/Start_Server.jpg b/src/.vuepress/public/assets/img/community/developers-guide/Start_Server.jpg new file mode 100644 index 00000000000..5de5c9f7483 Binary files /dev/null and b/src/.vuepress/public/assets/img/community/developers-guide/Start_Server.jpg differ diff --git a/src/.vuepress/public/assets/img/community/developers-guide/Tomcat_Run_Profile.jpg b/src/.vuepress/public/assets/img/community/developers-guide/Tomcat_Run_Profile.jpg new file mode 100644 index 00000000000..50afb0910e8 Binary files /dev/null and b/src/.vuepress/public/assets/img/community/developers-guide/Tomcat_Run_Profile.jpg differ diff --git a/src/.vuepress/public/assets/img/community/developers-guide/Tomcat_running_in_Eclipse.png b/src/.vuepress/public/assets/img/community/developers-guide/Tomcat_running_in_Eclipse.png new file mode 100644 index 00000000000..bf2909881c0 Binary files /dev/null and b/src/.vuepress/public/assets/img/community/developers-guide/Tomcat_running_in_Eclipse.png differ diff --git a/src/.vuepress/public/assets/img/community/developers-guide/WebUI_Classpath.png b/src/.vuepress/public/assets/img/community/developers-guide/WebUI_Classpath.png new file mode 100644 index 00000000000..b4b10123e10 Binary files /dev/null and b/src/.vuepress/public/assets/img/community/developers-guide/WebUI_Classpath.png differ diff --git a/src/.vuepress/public/assets/img/community/developers-guide/Web_Project_Settings.jpg b/src/.vuepress/public/assets/img/community/developers-guide/Web_Project_Settings.jpg new file mode 100644 index 00000000000..456f046c714 Binary files /dev/null and b/src/.vuepress/public/assets/img/community/developers-guide/Web_Project_Settings.jpg differ diff --git a/src/.vuepress/public/assets/img/community/preface/software-development/1200px-ADempiere_Repository_Structure.png b/src/.vuepress/public/assets/img/community/preface/software-development/1200px-ADempiere_Repository_Structure.png new file mode 100644 index 00000000000..cdb4fd96ae8 Binary files /dev/null and b/src/.vuepress/public/assets/img/community/preface/software-development/1200px-ADempiere_Repository_Structure.png differ diff --git a/src/.vuepress/public/assets/img/community/preface/software-development/Development_cycle.png b/src/.vuepress/public/assets/img/community/preface/software-development/Development_cycle.png new file mode 100644 index 00000000000..7521bf2f36b Binary files /dev/null and b/src/.vuepress/public/assets/img/community/preface/software-development/Development_cycle.png differ diff --git a/src/community/wiki/README.md b/src/community/wiki/README.md index 058dc6dbe89..a99490c342b 100644 --- a/src/community/wiki/README.md +++ b/src/community/wiki/README.md @@ -13,9 +13,9 @@ A work in progress. This page will become the table of contents of the ADempiere ## Table of Contents 1. [Preface](./preface/README.md) -2. [User Guide](a) +2. [Developer's Guide](./developers-guide/README.md) 3. [Business Functionality Guide](a) 4. [System Administrator's Guide](a) -5. [Developer's Guide](a) +5. [User Guide](./user-guide/README.md) 6. [Appendices](a) diff --git a/src/community/wiki/developers-guide/README.md b/src/community/wiki/developers-guide/README.md new file mode 100644 index 00000000000..eb8b569241b --- /dev/null +++ b/src/community/wiki/developers-guide/README.md @@ -0,0 +1,100 @@ +--- +title: Developer's Guide +category: Community +star: 9 +sticky: 9 +tag: + - Wiki +article: false +--- + +## Software Development + +- [Becoming a Developer](./becoming-a-developer.md) +- [Software Development Procedure](./software-development-procedure.md) +- [ADempiere Version Control](./adempiere-version-control.md) +- [ADempiere Best Practices](./adempiere-best-practices.md) +- [Software Testing and QA](./software-testing-and-qa.md) +- [Road Map](./road-map.md) + +## Releasing New Versions + +- [Creating a New Seed Database](./creating-a-new-seed-database.md) +- [Steps to Release](./steps-to-release.md) +- [Generating Windows Installers](./generating-windows-installers.md) + +## Development Environments for Testing and Customization + +- [Create your ADempiere development environment](development-environments-for-testing-and-customization.md) + - [Creating WebUI Workspace using Eclipse Webtool](./creating-webui-workspace-using-eclipse-webtool.md) + - [Create your ADempiere customization environment](https://wiki.adempiere.net/Create_your_ADempiere_customization_environment) + +## Understanding ADempiere + +- [Application Dictionary Philosophy](https://wiki.adempiere.net/Application_Dictionary_Philosophy) +- [Application Dictionary Overview](https://wiki.adempiere.net/Application_Dictionary) +- [Application Dictionary Layers](https://wiki.adempiere.net/Application_Dictionary_Layers) + +## Rapid Development + +- [ADempiere Rapid Development](https://wiki.adempiere.net/ADempiere_Rapid_Development) Overview + - [Virtual Columns](https://wiki.adempiere.net/Virtual_Columns) - Column SQL + +- [Development with Reports and Process](https://wiki.adempiere.net/Development_with_Reports_and_Process) + +- AD [Workflow](https://wiki.adempiere.net/Workflow) + - [Document Apporval Workflow](https://wiki.adempiere.net/How_to_Activate_Document_Approval_Workflow) + +## Advanced Development Documentation + +- [Development](https://wiki.adempiere.net/Development) Page +- [Development FAQ](https://wiki.adempiere.net/Development_Terms) +- [Centralized ID Management](https://wiki.adempiere.net/Centralized_ID_Management) +- [First Step for Developers](https://wiki.adempiere.net/First_Step_for_Developers) + - [Method Invocation Sequence](https://wiki.adempiere.net/Method_Invocation_Sequence) +- [When to use what Technology](https://wiki.adempiere.net/DevGuide_When_to_use) +- [Methods of Development](https://wiki.adempiere.net/Methods_of_Development) +- [Extending ADempiere](https://wiki.adempiere.net/Extending_ADempiere) + - [Model Validator](https://wiki.adempiere.net/ModelValidator) + - [Callout](https://wiki.adempiere.net/Callout) + - [Example Callout](https://wiki.adempiere.net/Callout_Code) +- [Rules](https://wiki.adempiere.net/Rule) and [Validator](https://wiki.adempiere.net/ModelValidator) + - [Rule](https://wiki.adempiere.net/Rule) + - AD [Validation Rule](https://wiki.adempiere.net/Validation_Rule) +- [Scripting](https://wiki.adempiere.net/Scripting) + - [Script_Callout](https://wiki.adempiere.net/Script_Callout) + - [Script_ModelValidator](https://wiki.adempiere.net/Script_ModelValidator) + - [Script_Process](https://wiki.adempiere.net/Script_Process) + +- [Process](https://wiki.adempiere.net/Process) + - [Calling a process from code](https://wiki.adempiere.net/Calling_a_process_from_code) + - [How to write an Adempiere Process](https://wiki.adempiere.net/Howto_write_an_Adempiere_process) + +- Extending Functionality + +- [Attribute Level Pricing](https://wiki.adempiere.net/Attribute_Level_Pricing) + +- Extending Specific Features + - [Zoom Across](https://wiki.adempiere.net/Extending_Zoom_Across) + +- [How to create a complete new module in ADempiere](https://wiki.adempiere.net/How_to_create_a_complete_new_module_in_ADempiere) + +- [WebUI](https://wiki.adempiere.net/WebUI) +- [Introduction to ZK WebUI](https://wiki.adempiere.net/Introduction_to_ZK_WebUI) +- [Creating WebUI Workspace](https://wiki.adempiere.net/Creating_WebUI_Workspace) +- [Configuring WebUI in Eclipse](https://wiki.adempiere.net/Creating_WebUI_Workspace_using_Eclipse_Webtool) +- [Creating WebUI Workspace using Sysdeo Tomcat Plugin](https://wiki.adempiere.net/Creating_WebUI_Workspace_using_Sysdeo_Tomcat_Plugin) +- [Migrating Swing to ZK WebUI](https://wiki.adempiere.net/Porting_Custom_Swing_Form_to_ZK) +- [ZK Enhancements](https://wiki.adempiere.net/Sponsored_Development:_Zk_Enhancement) +- [ZK Theme Development](https://wiki.adempiere.net/ZK_Theme_Development) +- [Swing](https://wiki.adempiere.net/index.php?title=Swing&action=edit&redlink=1) and [AD Forms](https://wiki.adempiere.net/index.php?title=AD_Forms&action=edit&redlink=1) + - [Object Model](https://wiki.adempiere.net/Form_Creation_Object_Model) +Example [Code Snippets](http://www.adempiere.com/index.php/Category:Code_snippets) +- [Packaging](https://wiki.adempiere.net/2Pack_Anatomy) +- [Groovy Development](https://wiki.adempiere.net/index.php?title=Groovy_Development&action=edit&redlink=1) + - [Example groovy Callout](https://wiki.adempiere.net/Examples:_Callout_and_Process_in_Groovy) +- [Contriburing to Adempiere](https://wiki.adempiere.net/index.php?title=Contriburing_to_Adempiere&action=edit&redlink=1) +- ["How To" Guides for developers](https://wiki.adempiere.net/Technical_HOWTOs) +- [Adempiere Technical Training](http://en.wikiversity.org/wiki/Adempiere_Technical_Training) in Wikiversity by Carlos Ruiz. + + diff --git a/src/community/wiki/developers-guide/adempiere-best-practices.md b/src/community/wiki/developers-guide/adempiere-best-practices.md new file mode 100644 index 00000000000..9aec0fcc59f --- /dev/null +++ b/src/community/wiki/developers-guide/adempiere-best-practices.md @@ -0,0 +1,617 @@ +--- +title: ADempiere Best Practices +category: Community +star: 9 +sticky: 9 +tag: + - Wiki + - Developer's Guide +article: false +--- + +## Overview + +This page outlines the practices to be followed for development within Adempiere. The rules and processes described are intended to ensure that the project is able to maintain the high standard of quality that is expected from a business critical application. + +## Team + +1. [Teo Sarca](https://wiki.adempiere.net/User:Teo_sarca) [[1]](mailto:teo.sarca@gmail.com) +2. [Cristina Ghita](https://wiki.adempiere.net/User:Redchris) [Metas](http://www.metas.ro/) : Libero stabilization +3. [Trifon](https://wiki.adempiere.net/User:Trifonnt) [D3Soft](http://www.d3-soft.com/) +4. [Victor Perez](https://wiki.adempiere.net/User:Vpj-cd) [e-Evolution](http://e-evolution.com/) +5. [Dominik Zajac](https://wiki.adempiere.net/User:Dominik) [BayCIX GmbH](http://www.baycix.de/) +6. [Carlos Ruiz](https://wiki.adempiere.net/User:CarlosRuiz) - just read links below\ +7. [Paul Bowden](https://wiki.adempiere.net/User:Phib) +8. [Redhuan D. Oon](https://wiki.adempiere.net/User:Red1) + +## Commit Policy + +1. The following guidelines describe the best practice when committing code in the Adempiere repository. + +### General principles + +2. We work as a team. A good team working together and sharing ideas will be smarter than any single developer. +3. The ability to commit to the Adempiere repository is a privilege, not a right. +4. To have autonomy you need a high degree of responsibility and authority.You get these by working with the team. There is no place for loners or loose cannons here. + 1. Committers are expected to take responsibility for their actions. + 2. If you break something, you should make every effort to fix it yourself, rather than relying on others to clean up for you. [2](https://sourceforge.net/p/adempiere/discussion/610548/thread/b6f78b46/) + +### Documentation + +5. All changes to the code base need to be adequately documented so that others can easily find out why a change was made and have the necessary information to allow them to assist with maintaining the new code. + 1. The level of documentation should be in proportion to the degree the proposed change will impact on the behaviour of Adempiere. +6. All commits must have an associated Bug Report or Feature Request. + 1. The absolute minimum requirement for documentation is that a SourceForge tracker is opened and referenced in the commit. + 2. Trackers must be descriptive. One-line trackers are not sufficient to allow others to complete a meaningful review of your work. + 3. If you're fixing a bug you should provide steps to reproduce the bug in GardenWorld or System. + 4. If it's not easily reproducible in GardenWorld, explain in detail what the issue is, in which scenarios the issue appears and the proposed solution (if any). + 5. If you are reporting a feature request also provide a suggested use case. When you have implemented the feature request you must then explain how to use the new functionality. + 6. Larger changes are better documented in a a wiki page that also provides end user guidance. + 7. It is not acceptable to leave it up to others to "read the code" to work out how your contribution works. [3](http://sourceforge.net/forum/forum.php?thread_id=2681108&forum_id=610548) +7. Technical Documentation. Ideally the committer should endeavour to provide some technical documentation. This ensures that if the original committer is unavailable, others will be able to maintain the code without resorting to reverse engineering. + +### Approval + +1. Bug fixing can be done directly. If you are confident that you have found a bug and that you have a fix that does not have any adverse side effects, it is acceptable to commit directly without waiting for +community consultation. + 1. However, if there is any doubt, committers are advised to request further feedback before proceeding. [4](http://sourceforge.net/forum/message.php?msg_id=5828131) +1. Feature requests require community approval. To ensure that all new features will be useful to the community at large and properly implemented a process of community consultation must be undertaken. + 1. This involves proposing the contribution, addressing any concerns raised by community members (paying particular attention to functional specialists), and receiving a positive vote for the request. See the + section on voting below. + 2. Getting community approval for implementing a feature request is not sufficient to guarantee acceptance of a contribution. All the other requirements outlined here must also be met. +2. New features entering trunk should be submitted for review in an separate branch or through a patch + 1. Community approval may be withheld until others are able to review the actual code, either by the code being committed to a "sandbox" branch, or submitted as a patch. + 2. Other committers may vote against a proposed feature until such a submission is provided for them, if they do so, they should make every effort to review the submission as quickly as possible. [5](http://sourceforge.net/forum/message.php?msg_id=5828131) + +### Implementation + +11. The implementation in code of a bug fix or feature contribution must adhere to the following guidelines. + 1. To integrate into trunk a contribution must be complete, documented and testable + 2. Do not commit half finished code into trunk in the hope that someone else will take it over. + 3. If you wish to contribute work that you are unable to complete, supply it as a patch or separate branch. [6](http://sourceforge.net/forum/message.php?msg_id=5828131) + +12. Don't drop existing elements or functions. + 1. Don't drop "not-added-by-you" things (db elements or functionalities). We must assume that any existing part of Adempiere may be being used by someone's implementation. + 2. Unless there is a good reason to drop it, for example functionality is really broken, do not drop it. + 3. If there is a valid reason then please first ask in forums before considering the drop. [7](http://sourceforge.net/forum/forum.php?thread_id=2667992&forum_id=610548) +13. Always review collateral effects of your changes + 1. Every time you touch one line of code or application dictionary please review the dependencies (collaterals). Eclipse helps a lot pointing to the name of the method/variable + right click + references -> +workspace. For other code (like callouts, processes, etc) sometimes you need to check the dictionary to see where is it called (I normally review Adempiere_pg.dmp).[8](http://sourceforge.net/forum/foru) +14. Do not commit a change if you only implemented it for one database +i. We officially support multiple databases and all changes should work exactly the same on both every database platform. Do not assume that someone else will port it for you. [9](http://sourceforge.net/foru +) and [10](http://sourceforge.net/forum/message.php?msg_id=5828131) +15. Support both Java 5 and Java 6 +i. We officially support both these versions of Java. If you are coding against Java 6 please ensure that code is backwards compatible with 5. [11](http://sourceforge.net/forum/message.php?msg_id=582813) + +16. Only use the current trunk version of ModelGenerator +i. There must be just one official version of ModelGenerator. Private versions of ModelGenerator must be avoided. [12](http://sourceforge.net/forum/forum.php?thread_id=2663645&forum_id=610548) + +### Code Style + +17. Code must be properly indented + 1. But don't re-indent fully working code just because it doesn't look exactly right in your IDE. +The code might be indented nicely in someone elses IDE and if we keep reformatting according to our particular IDE we'll end up with a lot of commits but nothing really done. We won't be able to track +"real" changes. [13](http://sourceforge.net/forum/message.php?msg_id=5828131) +18. Proper usage of variable names [14](http://sourceforge.net/forum/message.php?msg_id=5828131) +19. All comments and variables in english [15](http://sourceforge.net/forum/message.php?msg_id=5828131) +20. No duplicated code [16](http://sourceforge.net/forum/message.php?msg_id=5828131) +21. Use constants or MSysConfig instead of hardcoded things [17](http://sourceforge.net/forum/message.php?msg_id=5828131) + +### Committing + +22. Follow the best practices for using SVN when committing. [18](http://svn.collab.net/repos/svn/trunk/doc/user/svn-best-practices.html) +23. All commits should be atomic: + 1. that is they are the complete code patch that addresses a Bug Report [**BR**] or Feature Request [**FR**] in sourceforge. + 2. If the contribution is unusually large it may be committed in small parts but then commit should be distinct functional parts. + 3. Preferably a commit must solve one and only one tracker - this is to ease integration with other branches or maintained versions. +24. Commit Early in YOUR day: + 1. Only commit if you are around to support or even revert in case of a problems. +25. Update before commit: + 1. Do an SVN update and ensure all still compiles locally before you commit. +26. Reference the BR/FR in the commit comments: + 1. include the full url to the sourceforge BR/FR, but also include a short, but descriptive, comment that does not require the reader to go to the BR/FR in sourceforge unless they require details. Example: + +[ 2354040 ] Implementation Replication Mode, Type, Event + +Enhance replication to allow export and import of documents and then execute the document status action. + +27. Synchronise & Build: + 1. after committing sync again with the repository and confirm all still builds without errors. +28. On successful commit Update the BR/FR: + 1. include the SVN revision reference and set the status & resolution fields as appropriate. + +### Rules suggested on Nov-2007 to reach TRUNK + +[http://sourceforge.net/forum/forum.php?thread_id=1881039&forum_id=611167](http://sourceforge.net/forum/forum.php?thread_id=1881039&forum_id=611167) +29. Proof of stability. This should be base on community feedback on binary release. Optional: Production site, unit and functional test case. +30. Sample Data. There should be some sample data available. +31. Maintainer. Must have dedicated maintainer ( individual or company ). Must follow existing Adempiere Developer's criteria. +32. Branding and copyright issue. No vendor branding, must prove to be original work. +33. Migration script. Support all supported databases, i.e oracle and postgresql and pl/java +34. Migration scripts for ADempiere >342 + 353a shouldn't use or implement new pl/java functions. +35. Migration Process COMPLETE and documented. For new module that replace or enhance existing functionality, it is very important to have the migration process documented. + +## Voting + +### For new functionality + +36. Vote takes place in SourceForge forums or trackers + 1. Active members of the community are entitled to vote + 2. A minimum of 72 hours must pass from the call for a vote before the matter can be considered decided + 3. The vote is decided in favour of the simple majority of the participating voters. At least one vote most be received for a vote to count. + 4. A positive vote only indicates that the proposed new functionality is in principle suitable for inclusion in Adempiere. It does not override a fact that a particular implementation of that functionality must also meet all the other requirements listed above. + +## Suggestions about hiring sponsored developments to ease inclusion in trunk + +[http://sourceforge.net/forum/forum.php?thread_id=1785728&forum_id=611167](http://sourceforge.net/forum/forum.php?thread_id=1785728&forum_id=611167) + +37. See also [Sponsorship rules](https://wiki.adempiere.net/Sponsorship_rules) + +## Advices suggested on Jul-2007 + +### License GPLv2 + +38. Sponsored development must be released under "GPLv2 or any later version" +39. If some development is put in wiki, discussed with community, enhanced with community ideas, etc. +40. The best practice can be to release it with the same Adempiere license. Very possibly community would not help or opine in a sponsored development that will be released as proprietary. + +### Contributor Agreement + +41. All sponsored development must be contributed signing an Adempiere Contributor Agreement (just one agreement by developer) like the one proposed here: [Contributor_Agreement](https://wiki.adempiere.net/Contributor_Agreement) +42. Initially contributor agreements must be sent to a selected trustee. +43. This is helping to ensure the first clause. It's a common practice in Open Source projects after the SCO vs IBM case. + +### Credit for the Author + +44. It is especially important in an open-source project to ensure that the developers and authors of the code are given proper recognition for their work. The credit should include sufficient detail that future +developers working on that code can find information about the rational for the design and a point of contact for additional information. +45. As a minimum, each commit/patch should include modifications to file header that provide the credit for the author. The credit should include references to additional information in the trackers, feature requests +and/or patches by both reference number and a url. +46. Developers should add this information when submitting patches or code for commit. This will make it easier for others to commit the work on the developer's behalf. +47. Commiters should ensure that the information is included in the patches or code and, if not, add it. Commiters should, where practical, also include the author's name in the commit comment. The committer's +name should appear as the "author" (-u option in Mercurial) of the commit. [19](http://www.adempiere.com/FT/TT_meeting_minutes_December_5th_2011) + +~~~ +/****************************************************************************** + * Product: Adempiere ERP & CRM Smart Business Solution * + * Copyright (C) All Rights Reserved. * + * This program is free software; you can redistribute it and/or * + * modify it under the terms of the GNU General Public License * + * as published by the Free Software Foundation; either version 2 * + * of the License, or (at your option) any later version. * + * This program is distributed in the hope that it will be useful, * + * but WITHOUT ANY WARRANTY; without even the implied warranty of * + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. * + * See the GNU General Public License for more details. * + * You should have received a copy of the GNU General Public License along * + * with this program; if not, write to the Free Software Foundation, Inc., * + * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. * + * * + * @author , + * BF [ ] or FR [ ] Description about the bug tracker * + * URL of Tracker * + *****************************************************************************/ + +~~~ + +[See an example](http://adempiere.hg.sourceforge.net/hgweb/adempiere/adempiere/file/5c83f57ac3e8/client/src/org/compiere/apps/APanel.java) + +### Peer review + +48. Sponsored development must follow peer review from a committer to be included in trunk + 1. if the developer is a committer, then must have peer review from other committer (same as all contributions in trunk) + +### Tools used + +49. In order to ease inclusion in core, the development must follow guidelines from the project - about tool used for integration: + 1. SQL migration scripts + 2. if the developer have problems with migration scripts, he must at least provide 2pack package + +### Must follow Adempiere conventions + +50. Developer must follow Adempiere conventions, i.e. code, directory tree, naming +51. Adempiere conventions are not clearly written, but Adempiere is big enough to get some conventions just looking what currently we have. + +### Test Cases + +52. It would be good developer provide/document simple test cases for the contribution +53. It's a good advice for sponsors when hiring a developer put the condition that deliverables must include documentation and test cases. The developer must know if the money is enough to make such work. +54. TestFramework Prototype framework for creating user tests + +### Visibility + +55. Try to keep updated the advance in a wiki page +56. Simple advice that also can be put as a condition from sponsor to developer in order to maximize the community involvement. + +### Sponsored developments must be made in a branch and updated frequently + +## About branches + +57. Branches are allowed (and in fact they're encouraged) to conduct experiments, to work in specific projects or in tasks, or to coordinate team work. +58. Private branches are allowed - owner(s) of branch rule the branch (all these rules are suggested in this case, but the owner(s) can expand or shrink these rules) + +## About releases + +59. Official releases must come from trunk +60. Official release must be tagged as alpha, beta, release candidate or stable. +61. This is subject to the number of errors open, the completeness of functionalities, and other issues related to quality of release. +62. Unofficial releases are allowed from branches + 1. in this case the release must have the name of the branch + 2. in this case the release must NOT be tagged as alpha, beta, release candidate or stable, unless community votes and after a review of open bugs, completeness of functionalities, and other issues related to + quality of release. + +## Suggested policies for extensions + +### Meeting 2008-11-05 + +63. According to suggestions received on [meeting nov-5-2008](https://wiki.adempiere.net/CC_Meeting_Full_20081105) convoked by the [more boring ruler](https://wiki.adempiere.net/User:CarlosRuiz). + +### Generate ID's from centralized dict + +### Assign specific entity type and prefix rules + +64. It's suggested also to follow entity type and prefix rules for all columns and tables created. + +### Build on top and not changing kernel + +65. Sometime an extension might replace some code in core but that is usually just a problem in the core rather than changing the definition of an extension +66. Definition of kernel: common functionalities, like PO, like window management, etc - none related to business rules... + +### Work in a branch + +67. It's encouraged to work in an adempiere branch and open for adempiere committers. But anyways it can be analyzed if extension developer wants to open an own project in sourceforge (or any open source +hosting site). +68. You don't need permissions to experiment in your own branch/project - and add things to core. If you want something integrated in trunk you must follow rules stated in this document. +69. Extension developers must have a playground where they can develop without asking too much about permissions - following some recommendations to allow easy integration. + +### If several extensions are in competence - is suggested to let them compete as extensions, not including any on trunk + +### Integrating several extensions at the same time can lead to column collision problems + +### Follow the recommended extension architecture + +70. Write Callouts +71. Write ModelValidator +72. Don't generate model for your columns (but you can for your new tables), instead of this use the generic getters and setters available in PO.java + +### License + +73. License must be "GPLv2 or any later version". An explanation can be found at (term 9). + +### No hiding sources + +74. It's encouraged to avoid the SaaS loophole to hide sources (or any other loophole within this license). +75. Code must be open for everybody in any release. + +### Certification + +76. If you follow the suggested policies here - you can be certified as adempiere friendly extension - and we can consider including it within the official release. + +## Coding Standards + +### Suggestion & Questions Coding Standards + +### Coding Style + +77. See File:Libero-formatter.xml . +78. Do not use the conversion from Integer to int, Double to double and so on, because from java5 is doing autoboxing. +79. Allways use bracelets {}. It is improving code readability and can evict hard to detect bugs. +80. Don't use transaction names if is not necessary. Better put null. +81. Known issues: + 1. At present eclipse formatter is not supporting fluent interfaces [(see eclipse bug #196001](http://bugs.eclipse.org/bugs/show_bug.cgi?id=196001) + +### How to change parameters of existing method from ADempiere core + +82. ALWAYS keep the old method for backward compatibility and add the @deprecated tag in the javadoc of the method @deprecated since 3.5.3a. Please use {@link #myMethod(...)} instead +83. Search for all places from ADempiere core where the old method is using and replace with the new one. In this way you will leave the old method with no calls in core and ready to be dropped after some +releases. + +## How to use Adempiere Query class? + +### How to return only ONE persistent object? + +84. + + ~~~ + StringBuilder whereClause = new StringBuilder(); + whereClause.append("AD_Client_ID=?"); // #1 + whereClause.append(" AND AD_Org_ID=?"); // #2 + whereClause.append(" AND C_AcctSchema_ID=?"); // #3 + whereClause.append(" AND Account_ID=?"); // #4 + + MAccount existingAccount = new Query(ctx, I_C_ValidCombination.Table_Name, whereClause.toString(), null) + .setParameters(new Object[]{AD_Client_ID, AD_Org_ID, C_AcctSchema_ID, Account_ID}) + .first(); + ~~~ + +85. Use the interface to put the Table Name I_C_ValidCombination.Table_Name +86. Use the StringBuilder when the **Where Clause** is built +87. Use the final String whereClause when the **Where Clause** is not built If you know that your query should return ONLY one result, then you can assert this, and use **firstOnly** method instead of **first** method: + +88. + + ~~~ + count existingAccount = new Query(ctx, I_C_ValidCombination.Table_Name, whereClause, null) + tParameters(new Object[]{AD_Client_ID, AD_Org_ID, C_AcctSchema_ID, Account_ID}) + rstOnly(); + ~~~ + +### How to return ARRAY of objects? + +89. + + ~~~ + lic static MAchievement[] getOfMeasure (Properties ctx, int PA_Measure_ID) + { + al String whereClause = COLUMNNAME_PA_Measure_ID+"=?"; + t list = new Query(ctx, I_PA_Achievement.Table_Name, whereClause, null) + tParameters(new Object[]{PA_Measure_ID}) + tOrderBy(COLUMNNAME_SeqNo+", "+COLUMNNAME_DateDoc) + st(); + urn list.toArray(new MAchievement[list.size()]); + } + ~~~ + +### How to return ARRAY of objects and process elements? + +90. + + ~~~ + blic static MAchievement[] getOfMeasure (Properties ctx, int PA_Measure_ID) + { + ing whereClause = COLUMNNAME_PA_Measure_ID+"=? AND "+COLUMNNAME_IsAchieved+"=?"; + t list = new Query(ctx, MAchievement.Table_Name, whereClause, null) + tParameters(new Object[]{PA_Measure_ID, true}) + tOrderBy(COLUMNNAME_SeqNo+", "+COLUMNNAME_DateDoc) + st(); + (MAchievement achievement : list) + { + og.fine(" - " + achievement); + do some processing here + } + urn list.toArray(new MAchievement[list.size()]); + } + ~~~ + +### How to return one member of an object? + +91. + + ~~~ + lic static int getWindow_ID(String windowName) + { + retValue = 0; + ing whereClause = COLUMNNAME_Name+"=?"; + ndow win = new Query(Env.getCtx(), MWindow.Table_Name, whereClause, null) + tParameters(new Object[]{windowName}) + rst(); + urn = win.getAD_Window_ID(); + } + ~~~ + +### How to pass Timestamp parameter? + +92. + + ~~~ + estamp dateAcct = ...; + ing trxName = ...; + ingBuilder whereClause = new StringBuilder(); + reClause.append("C_CashBook_ID=?"); + reClause.append(" AND TRUNC(StatementDate)=?"); + reClause.append(" AND Processed=?"); + // + // + // + sh retValue = new Query(ctx, MCash.Table_Name, whereClause.toString(), trxName) + tParameters(new Object[]{C_CashBook_ID, TimeUtil.getDay(dateAcct), true}) + rst() + ; + #1 + #2 + #3 + ~~~ + +### How to use Query class with complex where clause: EXISTS? + +93. + + ~~~ + ingBuilder whereClause = new StringBuilder(); + reClause.append("C_Cash.AD_Org_ID=?"); + #1 + reClause.append(" AND TRUNC(C_Cash.StatementDate)=?"); + #2 + reClause.append(" AND C_Cash.Processed='N'"); + reClause.append(" AND EXISTS (SELECT * FROM C_CashBook cb"); + reClause.append(" WHERE C_Cash.C_CashBook_ID=cb.C_CashBook_ID AND cb.AD_Org_ID=C_Cash.AD_Org_ID"); + reClause.append(" AND cb.C_Currency_ID=?)"); + #3 + sh retValue = new Query(ctx, MCash.Table_Name, whereClause, trxName) + tParameters(new Object[]{AD_Org_ID,TimeUtil.getDay(dateAcct),C_Currency_ID}) + rst() + ; + ~~~ + +## How to use Adempiere Callout class? + +94. For new callout code i always recomend to use GridTabWrapper class that is wrapping an GridTab object to an "persistent interface". For more info, there is an example on javadoc of the class. I am copy-paste +here too: + +95. + + ~~~ + _Asset_Disposed bean = GridTabWrapper.create(mTab, I_A_Asset_Disposed.class); + estamp dateDoc = (Timestamp)value; + n.setDateAcct(dateDoc); + n.setA_Disposed_Date(dateDoc); + ~~~ + +Benefits: + +- cleaner code +- write algorithms once (and not 1 method for PO and other for GridTab) +- eliminate error prone strings + +## How to use PreparedStatement/ResultSet ? + +96. If you really need to use JDBC queries, then here is a template for that: + + ~~~ + final String sql = "''your SQL SELECT code''"; + PreparedStatement pstmt = null; + ResultSet rs = null; + try + { + pstmt = DB.prepareStatement(sql, trxName); + DB.setParameters(pstmt, new Object[]{...''parameters''...}); + rs = pstmt.executeQuery(); + while(rs.next()) + { + ''// process fetched row'' + } + } + // If your method is not throwing Exception or SQLException you need this block to catch SQLException + // and convert them to unchecked DBException + catch (SQLException e) + { + throw new DBException(e, sql); + } + // '''ALWAYS''' close your ResultSet in a finally statement + finally + { + DB.close(rs, pstmt); + rs = null; pstmt = null; + } + ~~~ + +## Always use DB.getSQLValue*Ex + +97. DB.getSQLValue*Ex methods which have same functionality as their counterpart but in case of an SQLException(checked) then a DBException(unchecked) will be thrown. +98. This will help us to assure data integrity and to distinguish between exceptions and null values. See: [FR 2448461 - Introduce DB.getSQLValue*Ex methods](http://sourceforge.net/tracker/?func=detail&atid=879335&aid=2448461&group_id=176962) + +## Always use Trx.run methods + +99. If you want to run a fragment of code that is changing the database data, and if something if failing you need to rollback entire transaction or to rollback to a savepoint, then Trx.run methods are the best option: +100. Trx.run(TrxRunnable r) - creates a new transaction, runs the runnable object and if something fails then rollbacks the transaction and throw AdempiereException (extends RuntimeException). If all is ok, the +transaction is commited. +101. Trx.run(String trxName, TrxRunnable r) - similar with previous run method, but instead of creating a new transaction it is creating a new savepoint. + +~~~ +Example 1: +... +/** +* saves the partner, user and employee +*/ +private void cmd_save() +{ +Trx.run(new TrxRunnable() { +public void run(String trxName) { +MBPartner bp = new MBPartner(getCtx(), bpartner_id, trxName); +bp.setValue(fValue.getText()); +bp.setName(fName.getText()); +if (bp.get_ID() <= 0) { +bp.setIsEmployee(true); +} +bp.saveEx(); +...... +} +}); +} +Example 2: +... +/** +* get Connection object +*/ +private void cmd_save() +{ +Trx.run(new TrxRunnable() { +public void run(String trxName) { +try +{ +Trx trx = Trx.get(trxName, true); +conn = trx.getConnection(); +... +} +catch (SQLException e) +{ +throw new AdempiereException(e); +} +} +}); +} +~~~ + +## References + +- [EE Best Practices](http://www-128.ibm.com/developerworks/websphere/techjournal/0701_botzum/0701_botzum.html?ca=dgr-jw17Java-EE-Best-Practices) + +- [Precise Java](http://precisejava.com/) + +## Sugesstion & Questions Coding Style + +102. When on a single thread class, StringBuilder should be used for String concatenation. If the class is not single threaded, then, StringBuffer should be used for String concatenation. + +## Testing Policy + +103. Submit your changes to local testing or a peer review before committing unless you are approved by 1st level committer +104. Publish your test results pls edit according to SF link findings above) + +### Test Units + +105. The use of [FitnesseSlim](https://wiki.adempiere.net/FitnesseSlim) is thoroughly explored in [Cost Engine/Testing](https://wiki.adempiere.net/Cost_Engine/Testing) with a complete case [contribution](http://sourceforge.net/projects/adempiere/files/Adempiere%20Packages/CostEngineTesting.pdf/download). + +## Documentation Policy + +106. Document your sourcecode changes in this wiki under appropriate topic. +107. Solicit help from others if you cannot document well. Or just start a stub and allow others to expand it. +108. Intentionally hiding information may get your contribution categorised as proprietary and not fit for admission into trunk. +109. New features, windows or fields need help text at least in english. + +## Communication + +### Bringing ideas (or collecting votes) for a development or bug fix + +110. open a discussion forum and try to keep the discussion in forums (it can be in a tracker, but we have noticed that forums get much more attention than trackers) +111. after the discussion ends in some proposal then open a tracker - and add a link in the comment to the forum THREAD (to the thread, not to a single message) +112. after tracker is opened try to keep the discussion on the tracker - unfortunately we cannot close the forum thread (still, maybe in phpbb we can) + +### When committing + +113. Try to keep all communication related to one theme in one single thread +114. Every commit must have a related tracker previously opened +115. It's recommended the commit message have a link to the tracker and a brief explanation of what was done +116. After the commit add a comment in tracker pointing to the review, it's recommended to add a link to the svn log +117. To make comments about code please use the tracker - this is to keep ALL information related in just one site + 1. Please avoid writing to the cvslog maillist - writing comments there is spreading related information, so people trying to follow history of an issue must review forums, then trackers, then maillist. This + policy is trying to keep all information related and linked properly. + +## Lawful Vote and Review of Best Practices + +118. For more info please see Project_Charter#Political. +119. Review is now ongoing until 31st December 2008, where it is accepted and voted en bloc by the whole community in January 2009. +120. It has to be a full turn-out consensus vote first time round from the active common members in order for it to carry the weight of enforceable law. +121. Subsequent reviews shall be periodic minimally each quarter and not amended adhoc prior to review date. +122. Next review date should be not earlier than March 2009. + +## Mentor Policy + +123. All committers should also seek a mentor or coach among the senior committers already mentioned in the Commit Committee. +124. Mentees (who are under Mentors) have to assist in providing review and other administrative assistance (this is due to resources constraints at the moment to manage the team). + +## Adempiere Official Domains and Subdomains + +### Fair use + +125. Some policies were proposed on this thread [()](http://sourceforge.net/projects/adempiere/forums/forum/610546/topic/3426534): + 1. Money collected from these sites (i.e. advertising) must go to German Foundation and help to sustain the project + 2. Site sponsor, site seeder, and site maintainer can be advertised within a sponsors page and with a little box at the end of each page + 3. If there are zkwebui interface then some advertising links are allowed in the initial page + 4. Collecting visitor statistics must be made public for all community, or at least to project admins on request + 5. The sites must not collect user information - ask for registration - or anything about (unless by the nature of the site it's needed) + 6. No forums or support must happen on these sites - all support must be redirected to sourceforge forums + 7. No wiki must be set up on these sites - all documentation must be redirected to adempiere wiki + 8. The maintainer must be active, it the website becomes outdated more than one month then we must consider dropping the site, or calling for a new maintainer. + 9. Adempiere citizens can call for vote on closing a site if there are at least 3 persons that think it's being abused or not following fair use practices. + 10. Name of the subdomain must be previously discussed with community to reflect the goal and status of the site + 11. Citizens can ask to add or cut advertising on the subdomain sites (via voting process) diff --git a/src/community/wiki/developers-guide/adempiere-version-control.md b/src/community/wiki/developers-guide/adempiere-version-control.md new file mode 100644 index 00000000000..79f8b4e0b9d --- /dev/null +++ b/src/community/wiki/developers-guide/adempiere-version-control.md @@ -0,0 +1,85 @@ +--- +title: ADempiere Version Control +category: Community +star: 9 +sticky: 9 +tag: + - Wiki + - Developer's Guide +article: false +--- + +::: info Note + +As of Release 380, 15 January 2015, the main ADempiere repository has moved to GitHub along with the entire history of the main branches. This document described the process of working with GitHub as well as the instructions for SourceForge. The page will be a work in progress for a few days. + +::: + +## The ADempiere Project Repository + +The main repository for ADempiere can be found on the GitHub site at [https://github.com/adempiere/adempiere](https://github.com/adempiere/adempiere). + +Before proceeding, please refer to the [Git SCM Documentation](https://git-scm.com/doc). + +To collaborate with the ADempiere team, we use the git FORK and PULL model. From the [GitHub website](https://docs.github.com/es/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#fork--pull) + +The fork & pull model lets anyone fork an existing repository and push changes to their personal fork without requiring access be granted to the source repository. The changes must then be pulled into the source repository by the project maintainer. This model reduces the amount of friction for new contributors and is popular with open source projects because it allows people to work independently without upfront coordination. + +Refer to the GitHub article on [Pull Requests](https://docs.github.com/es/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) for more information and instructions on how to get started. + +## Summary Instructions + +The setup is easy. Follow these steps: + +- Install the **Git Software**. You can work with the Git command line or any of a number of Git GUI tools. As the repository is on GitHub, it is recommended to follow the GitHub setup procedures. +- Create a GitHub account +- Create your personal fork of the ADempiere project +- Create a local clone of your personal fork +- Follow the instructions in Create your ADempiere development environment, Creating WebUI Workspace using Eclipse Webtool and Create your ADempiere customization environment. +- Start developing! +- Commit your work to your own fork. Follow the ADempiere Software Development Procedure for branch naming. +- Send a pull request to the ADempiere project. + +### Cloning a Repository + +Cloning a repository to your local computer is simple. Follow the instructions with the GitHub software or your GUI tool, many of which allow for cloning a GitHub repository to a local computer with a few mouse clicks. If you want to do it from the command line, + +~~~ +# Navigate to the parent directory where the repository will be placed and type the following command +C:\dev\repos\github>git clone [url] +~~~ + +This will create a directory using the url project name, initialize a .git directory inside it, pull down all the data for that repository, and check out a working copy of the latest version. If you go into the new directory, you’ll see the project files in there, ready to be worked on or used. + +To change the name of clone directory use the following + +~~~ +# Navigate to the parent directory where the repository will be placed and type the following command +C:\dev\repos\github>git clone [url] +~~~ + +### Cloning the Repository with a Slow Connection + +To clone a repository over a slow or intermittent Internet connection, try using git fetch instead of clone as follows: + +~~~ +# Create a directory for the repo and change to it +C:\dev\repos\github>mkdir adempiere + +C:\dev\repos\github>cd adempiere + +# Initialize the repository +C:\dev\repos\github\adempiere>git init +Initialized empty Git repository in C:/dev/repos/github/adempiere/.git/ + +# The default reference to the source repository in a clone is "origin". Clone your +# personal fork from your account . +C:\dev\repos\github\adempiere>git remote add origin https://github.com//adempiere.git + +# Fetch the contents. +C:\dev\repos\github\adempiere>git fetch + +# Update to the current master branch - for example +C:\dev\repos\github\adempiere>git reset --hard origin/master +~~~ + diff --git a/src/community/wiki/developers-guide/becoming-a-developer.md b/src/community/wiki/developers-guide/becoming-a-developer.md new file mode 100644 index 00000000000..e71e7aa84c4 --- /dev/null +++ b/src/community/wiki/developers-guide/becoming-a-developer.md @@ -0,0 +1,34 @@ +--- +title: Becoming a Developer +category: Community +star: 9 +sticky: 9 +tag: + - Wiki + - Developer's Guide +article: false +--- + +A Developer in the ADempiere bazaar is a person who contributes code, documentation or other work that is of value to the community. Anyone can become a Developer by making contributions. It is one of the most challenging and rewarding aspects of being involved in an open source community project. + +## Becoming a Developer + +To gain write access to the SourceForge repositories, all a person has to do is ask one of the project admins found on the [SourceForge ADempiere Develop page](https://sourceforge.net/projects/adempiere/develop). There is no vote or process to follow. However, its best not to make the request one of the first things you do. Contribute first, then ask. If the admins recognize you from your activity on the forums and in the trackers, you will get a quick positive response. + +Being a Developer with write access to the source code does not mean that you can immediately begin committing changes to the development branch. You must respect the [Software Development Procedure](). You can create your own repository for contributions and develop freely within that directory. In the main code repository, you will need permission before you can create a branch or start development on a new feature. + +After you have proven yourself as a developer, you can ask to join the community as a citizen. Eventually, you can be given the status of Committer with access and responsibility for the main code repository. + +## Accessing the Code Repositories on SourceForge + +To access the code, you will need to use mercurial and git and a few extentions. See the instructions in [ADempiere Version Control](). + +Next, learn about the ADempiere repository structure. Visit the [ADempiere site](http://sourceforge.net/projects/adempiere/#) on SourceForge. Under tools, both SVN and Mercurial are listed but Mercurial is the active version control system in use since the summer of 2011. + +Most of the work being performed on the code is performed in branches on the main repository "code". The [Software Development Procedure]() describes the branching methods used. + +Once you have local repositories setup, you can [Create your ADempiere development environment] and enjoy. + +If you have any problems or questions, reach out on the [Source Forge developer forums](http://sourceforge.net/p/adempiere/discussion/610548/). + + diff --git a/src/community/wiki/developers-guide/create-your-adempiere-development-environment.md b/src/community/wiki/developers-guide/create-your-adempiere-development-environment.md new file mode 100644 index 00000000000..c58900ebae7 --- /dev/null +++ b/src/community/wiki/developers-guide/create-your-adempiere-development-environment.md @@ -0,0 +1,29 @@ +--- +title: Create your ADempiere Development Environment +category: Community +star: 9 +sticky: 9 +tag: + - Wiki + - Developer's Guide + - Releasing New Versions +article: false +--- + +This tutorial will show you how to customize the ADempiere core software without making changes to the ADempiere project directly. Customization changes are instead included in customization.jar and zkcustomization.jar which can be deployed in the ADempiere install. + +## Introduction + +Sometimes you realize that ADempiere does not perfectly suit your needs and you need to make some changes to parts of the source code. Some customizations are not possible to achieve through ADempiere’s brilliant [Application Dictionary](a) and you have to modify the source code for that. The recommended way of customizing the software is to do it in a separate project. There you can create your customized classes and generate the customization jar archives. + +## How to setup up your environment +You will need to have two projects in your development environment: one for the ADempiere project and one for your customized code that will depend on the ADempiere project. + +## Create the ADempiere Project + +1. If you haven't already done so, follow the [ADempiere Version Control](./adempiere-version-control.md) process to checkout a branch of the ADempiere project. +2. [Create your ADempiere development environment](./create-your-adempiere-development-environment.md) and, if you are modifying the zk interface, [Creating WebUI Workspace using Eclipse Webtool](./creating-webui-workspace-using-eclipse-webtool.md) +3. Build (using utils_dev/build.xml), install, setup the software (to create the .properties file) and import the database seed. +4. Modify the launch configurations as required and test that you can run the client and zk interfaces. +5. You now have the main ADempiere project created. Changes to this project should be made as part of the [Software Development Procedure](./software-development-procedure.md) to fix bugs, add features and generate common code that will be shared by all ADempiere implementations. + diff --git a/src/community/wiki/developers-guide/creating-a-new-seed-database.md b/src/community/wiki/developers-guide/creating-a-new-seed-database.md new file mode 100644 index 00000000000..7ece0950ef1 --- /dev/null +++ b/src/community/wiki/developers-guide/creating-a-new-seed-database.md @@ -0,0 +1,78 @@ +--- +title: Creating a New Seed Database +category: Community +star: 9 +sticky: 9 +tag: + - Wiki + - Developer's Guide + - Releasing New Versions +article: false +--- + +One of the key task in a release is migrating the seed databases to the release version. The seed database then becomes the "reference database" that can be used to migrate production databases to the release version. + +::: warning Caution! + +This process is intended for seed database generation. While it may work for migrating production databases, it is not recommended to do so. The steps are based on the assumption that everything is done in order and the database is in a known state to start with. With a production database, this may not be the case and errors can be created. For production databases, use the Migrate tool which can be launched with $ADEMPIERE_HOME/utils/RUN_Migrate.[sh/bat]. + +::: + +### Since Release 3.8.0 + +The following process can be followed to update the seed: +1. Clean/purge your repository and update to the state of the release. +2. Update the project repository adempiere/migration/build.properties file to set the "release" variable correctly for the release. For example release="380lts". +3. Ensure the migration folders are named correctly - follow the same pattern as the previous releases. The project adempiere/migration folder will contain a number of folders of the form `-` with sub- +folders for each database and for the XML files. The build process will copy any directory that includes the release string - for example /370lts-380lts/* and /380lts-release/* - as long as the directory and sub- +folders contain sql or xml files. The build/install process will copy these directories to $ADEMPIERE_HOME/migration/*. +4. Compile a build of the software at the release version. +5. Install the software and RUN_Setup to configure it for the target database +6. From the previous release, copy the seed file - either Adempiere.jar or Adempiere_pg.jar to the $ADEMPIERE_HOME/data directory - overwrite the ones installed. +7. Import the previous seed into the database with RUN_ImportAdempiere.[sh|bat] - this will put the database in the state of the previous release. Don't use the current seed if its been updated during development. +Rather, return to a known release state and migrate from there. This is similar to what users will experience in the field so its best to make sure it works. +8. Apply any SQL as indicated below. Following 380 there shouldn't be any SQL, but if features with SQL were added to the release, there may be some to apply. Check the $AEMPIERE_HOME/migration folder +for sub-folders related to the databases. +9. Import the xml migration files as follows: + 1. From the command line, execute the batch file RUN_MigrateXML.[sh|bat]. This will import all XML files that were installed in the $ADEMPIERE_HOME/migration directory by the build & install +process. The command can be run multiple times without harm. + 2. From the client, if it can run with the past seed, you can also log in as the System Administrator and use the process "Import Migrations from XML". Point the File Name dialog at the +$AEMPIERE_HOME/migration folder and select the "Apply" check box. You can run the process without selecting apply, but there may be errors if newer migration files depend on the application of +older ones. You can run the process multiple times without harm. +1. Verify the logs show no error messages. If necessary, fix errors in the XML or code and repeat the import and migrate process until there are no errors. +2. Export the new seed database using RUN_DBExport.[sh|bat] +3. Rename the .dmp file to Adempiere.dmp for Oracle and Adempiere_pg.dmp for Postgres. Do the same for the log file. +4. Jar the .dmp and log file to into Adempiere.jar or Adempiere_pg.jar. +5. Execute RUN_ImportAdempiere.[sh|bat] and verify that the database loads without error. +6. Start the client and verify that there are no errors or warnings about database/software version differences. +7. Repeat the process with the other database. Hopefully, there will be no errors, otherwise, you'll have to fix them and redo the first database. +8. Copy the new seed files to the repository adempiere/data/seed directory, replacing the files that are there. +9. Commit the new seed files and any corrections that were made to the xml or code. +10. Update the wiki [Steps to Release](./steps-to-release.md) + +In summary: + +~~~ +RUN_ImportAdempiere +RUN_MigrateXML +RUN_DBExport +~~~ + +### Previous to 3.8.0 Applying SQL Migration Files + +Prior to release 3.8.0, the migrations were applied by SQL files which can be applied in a number of ways. The key points are: + +- the scripts should be applied in order. The files should have names that start with numbers (023_xxx.sql for example) and they should be applied in ascending order. +- unlike the xml migrations, there is no way to roll-back the SQL changes once they have been applied. Back up a production database before you apply the SQL. + +Since 3.15, the SQL files are stored in the project `adempiere/migration/-/` folder in sub-folders for each database. + +Applying the SQL is easy with any of a number of SQL tools (i.e. you can use dbvisualizer, Toad, sqlplus or [sqldeveloper](http://www.oracle.com/technology/products/database/sql_developer/index.html) to Oracle, or you can use [pgAdmin](http://www.pgadmin.org/) if your database is PostgreSQL). Its also possible to use the command line database tools. + +Perhaps the easiest way is to use the ANT build process in Eclipse. In the project repository adempiere/migration directory, copy the oracle.properties.template to oracle.properties (or the same with postgres.properties.template) and edit the file accordingly. Then, in each folder that contains the sql files, you should find an ANT build.xml file. Execute this as an ant build and it will apply the sql in the proper order. You can copy the build.xml file to other directories if you need to as long as the directory is below the migration directory. + +Following the application of the sql files, there may be a folder called PostMigration in the same folder as the SQL files. Apply all the scripts contained in this folder. Finally, run the scripts in the adempiere/migration/processes_post_migration folder for the respective database. + +Through the entire process, ensure each script is executed without errors. + +One of the challenges of migrating a database with SQL is knowing what SQL files were applied previously. When generating a new seed, always start from the previous seed. diff --git a/src/community/wiki/developers-guide/creating-webui-workspace-using-eclipse-webtool.md b/src/community/wiki/developers-guide/creating-webui-workspace-using-eclipse-webtool.md new file mode 100644 index 00000000000..a4bb714245c --- /dev/null +++ b/src/community/wiki/developers-guide/creating-webui-workspace-using-eclipse-webtool.md @@ -0,0 +1,146 @@ +--- +title: Creating WebUI Workspace using Eclipse Webtool +category: Community +star: 9 +sticky: 9 +tag: + - Wiki + - Developer's Guide + - Releasing New Versions +article: false +--- + +## Overview + +This article is a follow-on to [Create your ADempiere development environment](create-your-adempiere-development-environment.md) and describes how to modify the ADempiere project and your development environment to enable debugging of the zk webui using the Eclipse Webtool. Eclipse Webtool support was added in version 341. This additions allows you to run or debug the Zk web client using Eclipse webtool (Europa JEE and above ) and Apache Tomcat. + +## Setup the Project to Include the Webtool Support + +Before you start, see [Create your ADempiere development environment](./create-your-adempiere-development-environment.md) and ensure you can build and debug the swing client. + +### Aditional checklist + +- If you do not have an Eclipse Java EE version, you have to install in your Eclipse the plugins Eclipse Java EE Tools, JST Server Adapters and JST Server Adapters - Extensions. Otherwise, you will not see nor configure the Server view in Eclipse. +- Make sure you call the menu entry Help/Install new Software and in the field Work with the url for your version, e.g. for Luna: . +- It may be necessary that you have to configure Tomcat manually (according to ): Copy directory /your-tomcat-base-directory/webapps/ROOT to /your-workspace/.metadata/.plugins/org.eclipse.wst.server.core/tmp0/wtpwebapps. + +As the webtool is not setup by default, there is a bit of work to do each time you update the main project branch. Here are the steps: + +1. Checkout the ADempiere branch of interest and build it using the ant build in utils_dev/build.xml. +2. Open the Properties for the ADempiere project +3. Select Project Facets and click the link, "Convert to faceted form..." +4. Confirm that Dynamic Web Module is selected (Version 2.5 is OK.) +5. Confirm that Java is selected (select a JAVA version compatible with the code in the project) +6. Close the Project Facets and click Web Project Settings in the Project Properties dialog. This will show an error :"Contect Root cannot be empty". This is a problem with the eclipse luna version and you'll need to +check that the following "natures" are included in the eclipse .project file (there may be others but you need at least these two): +`` +`org.eclipse.wst.common.modulecore.ModuleCoreNature` +`org.eclipse.wst.common.project.facet.core.nature` +`` +7. Refresh the project and look at the Project Properties, Web Project Settings again. You should see the context root as "webui". +8. Now add servers. Its easiest to do this by right clicking in the server tab and selecting "New" or clicking the link to add servers if you see it. In the dialog that appears you can select the server you want to use and +download it to a directory. Apache Tomcat V6.0. installed in a directory like c:\dev\apache will work. The server should identify the available web projects and you can add the ADempiere project to the server. +9. Right click the server and select Run. Note that this won't work but it will publish the project and create a launch configuration for it. +10. Edit the launch configuration and add the following to the arguments: +-DPropertyFile=${adempierePropertiesFile} +-DADEMPIERE_HOME=${ADEMPIERE_HOME} +(Note: These arguments use variables but you could replace the variable with the relevant paths. The adempiere.properties file needs to exist which is why you need to build and install ADempiere.) +11. Save the configuration. +12. Run the server launcher again from the debug configuration. Check the console for errors. It should startup normally. +13. Once the server has started, open a browser and go to localhost:port/webui. Usually, Tomcat uses port 8080. You should see the standard login page. You can now insert breakpoints in the webui code and interact +with the code from the browser. +14. To make it easier to reproduce these steps, make a stash of these changes in git and reapply them from the stash when you switch to a new branch. + +To customize the zk interface, see Create your ADempiere customization environment. + +If you have any questions, please join our chat [(http://www.adempiere.net/web/guest/chat-on-line)](http://www.adempiere.net/web/guest/chat-on-line). + +- If you want that ADempiere ZK opens in Eclipse +- select ADempiere Project +- Right mouse click +- select as you please Run As/Run on Server or Debug As/Debug on Server +- In the opening dialog select server and resource, press finish +- The Adempiere ZK login dialog opens in an Eclipse view. +- Result + +![Tomcat_running_in_Eclipse](/assets/img/community/developers-guide/Tomcat_running_in_Eclipse.png) + +## Older Instructions + +::: info Note + +This article is based on an older version of eclipse. While the screen shots will not match exactly, the process is similar. + +::: + +You can verify that everything is in place by checking the project properties: + +- Project Facets (do not change anything here.) + +![Project_Facets](/assets/img/community/developers-guide/Project_Facets.jpg) + +- Web Project Settings + +![Web Project Settings](/assets/img/community/developers-guide/Web_Project_Settings.jpg) + +## Install Tomcat Runtimes + +First, you need to install a Tomcat runtime for the deploying and running of the zk Web Client. Use Tomcat 5.5+ + +To install a new Tomcat runtime, open the preferences dialog **Window->Preferences** and select the **Server->Installed Runtimes**. Use the **Search** button to locate your tomcat installation home folder. + +![Installed_Runtimes](/assets/img/community/developers-guide/Installed_Runtimes.jpg) + +## Define a New Server + +At the Servers view, right click to open the context menu and select New->Server. + +If server view is not visible then you can use Window→Show View→Others ... to open it. + +![New_Server](/assets/img/community/developers-guide/New_Server.jpg) + +- Select the correct server type and the server runtime you have setup earlier. + +![Define_a_new_server](/assets/img/community/developers-guide/Define_a_New_Server.jpg) + +- Add your project to the server instance to be created + +![Add_Project](/assets/img/community/developers-guide/Add_Project.jpg) + +- The created server instance is now ready for use. Just Start the server once and then stop it. Do not try to debug it at this moment. + +![start_server](/assets/img/community/developers-guide/Start_Server.jpg) + +## Define location of ADempiere property file and ADempiere home + +Now you have to define the location of your existng working 'Adempiere.properties' file and ADEMPIERE_HOME as system parameter for your Tomcat Instance. To do so, select Run->Open Run Dialog... and select the server instance you have created. Note Note that the entries for your server instance in the Run dialog will only be created after you have start it for at least one time. Select the arguments tab and append your property file path and home parameter at the end of VM arguments. + +It is highlighted in the pictures below: + +![tomcat_run_profile](/assets/img/community/developers-guide/Tomcat_Run_Profile.jpg) + +[Hengsin](https://wiki.adempiere.net/User:Hengsin) 01:11, 4 August 2008 (EDT) + +To avoid the problme "NoClassDefFoundError" you need to following the guidlinse suggested below in 'Trouble Shooting'. So, first follow that instruction, before you debug the zk webui. + +## Trouble Shooting + +I had a problem to start Tomcat with "NoClassDefFoundError". Missing class path to adempiere jars. Solved by editing run configuration. Go to classpath section at user entries add external libs from tomcat\lib (or tomcat\server\lib) than add project - AdempiereTrunk + +Apache jars needs to be at the first place in the classpath. See the image carefully along with the description below. + +- Bootstrap Entries + - JRE Library +- User Entries + - tomcat_dir/bin/*.jar + - tomcat_dir/server/lib/*.jar + - Adempiere Project + - Adempiere Libraries + +![webui_classhpath](/assets/img/community/developers-guide/WebUI_Classpath.png) + +## See Also + +- [Youtube: Servlet development using Eclipse and Tomcat](http://www.youtube.com/watch?v=EOkN5IPoJVs) +- [Create and Run Your First ZK Application with Eclipse](http://books.zkoss.org/wiki/ZK_Installation_Guide/Quick_Start/Create_and_Run_Your_First_ZK_Application_with_Eclipse_and_ZK_Studio) +- Q: [Debugging ZK webUI](http://sourceforge.net/projects/adempiere/forums/forum/610548/topic/4852616) diff --git a/src/community/wiki/developers-guide/development-environments-for-testing-and-customization.md b/src/community/wiki/developers-guide/development-environments-for-testing-and-customization.md new file mode 100644 index 00000000000..2691941796b --- /dev/null +++ b/src/community/wiki/developers-guide/development-environments-for-testing-and-customization.md @@ -0,0 +1,328 @@ +--- +title: Create your ADempiere Development Environment +category: Community +star: 9 +sticky: 9 +tag: + - Wiki + - Developer's Guide + - Releasing New Versions +article: false +--- + +Creating a development environment is an exciting first step to becoming a developer with ADempiere. The development environment will allow you to test and debug the application and make changes back to the community. Before you begin, you should be familiar with the [Software Development Procedure](./software-development-procedure.md) and [ADempiere Version Control](./adempiere-version-control.md). To test the Web User Interface (webui) you will need to follow the steps in [Creating WebUI Workspace using Eclipse Webtool](https://wiki.adempiere.net/Creating_WebUI_Workspace_using_Eclipse_Webtool) after you create your development environment. It is also recommended that you create a separate project for customization work that will not be shared with all ADempiere users. See [Create your ADempiere customization environment](https://wiki.adempiere.net/Create_your_ADempiere_customization_environment) for more information. + +If you have any issues, please join our [chat](http://www.adempiere.net/web/guest/chat-on-line). We'd be happy to help. + +## Preparing your Environment + +Download and install the Java JDK from the [Oracle website](http://www.oracle.com/us/technologies/java/overview/index.html). You will need the version of the Standard Edition (SE) or Enterprise Edition (EE) Java Development Kit (JDK) that works with the version of software you are compiling. For some of the recent versions, these are: + +- ADempiere 3.6 -- requires Java 6 +- ADempiere 3.7 or 3.8 -- requires Java 7 +- ADempiere branch 380#002 -- requires Java 8 + +Follow the installation instructions and set the environment variable JAVA_HOME to point to the installed JDK and add %JAVA_HOME%\bin to your PATH environment variable. + +::: info Note + +You can have multiple JDK versions installed and change which one you use by changing where JAVA_HOME points. Also, use the commands "which" on linux and "where" on dos to see where the called version is installed and "java -version" to check the version. + +::: + +Download and install a database. You can use PostgreSQL, Oracle or MySQL. PostgreSQL is recommended. Read more at [Database Server Installation & Setup](A). + +::: info Note: + +if you have access to a database server, you can use that rather than install a local copy of the database. + +::: + +Download and install the latest version of the Eclipse Integrated Development Environment (IDE) for Java EE Developers from the [Eclipse web site](https://www.eclipse.org/). + +## Download the ADempiere Source + +Download, install and configure your version control tools. See [ADempiere Version Control](./adempiere-version-control.md) for instructions. You may find tools that integrate with Eclipse directly but it is recommended to use those that include the latest versions of Mercurial and Git. Once you have your pristine and working clones created, you should update the working clone to the desired branch head. + +You can import the ADempiere project and other projects/modules into your IDE as follows: + +- Open Eclipse, java perspective, package explorer view +- Eclipse menu->File->New->Project +- In the following dialog, select "Java Project" and "Next" +- Type in "ADempiere" as the Project name +- Deselect the "Use default location" check box and set the Location to point at your working repository location (e.g. c:\dev\repos\workspace\adempiere). The wizard will automatically create the project from the existing source. Click "Next" and then "Finish". + +::: info Note + +In older versions of Eclipse, you may have to check the radio button "Create project from existing source" and browse to the project or module you want to include. + +::: + +## Compile and Debug ADempiere + +Use Eclipse to compile, build and debug/run ADempiere as the client or as a web application. + +Before you can run or debug the application, you have to: + +- configure Eclipse; +- ensure the application compiles properly; +- perform a "build" of the application; and +- import the seed data into the database + +An alternative way to get started is to install the latest version of ADempiere client on your development computer. See [Installing ADempiere Manually](a). This will ensure the setup parameters work and that the database seed is loaded properly. Most importantly, it will create a number of files that will be useful when you want to launch an instance of ADempiere from Eclipse. From the ADempiere home directory where the software was installed, these files are: + +- adempiereEnv.properties - copied from adempiereEnvTemplate.properties, this file defines the environment used to setup ADempiere. +- adempiere.properties - this file is generated by the setup process and shouldn't be edited. Once created, you can copy and rename it to other locations and use it in the launch configurations described below so you change configurations easily. This will allow you to change target databases or ports as required to test your application. +- utils->myEnvironment.bat/sh copied from myEnvironmentTemplate.bat by the setup process. Generally, you shouldn't edit this file directly but use the run_setup/run_silentsetup scripts. + +You can customize these files and keep a copy of them in a separate location in case they are overwritten by the version control processes. + +### Configure Eclipse + +Before you can compile the ADempiere software, there are a few things you can do to make the process easier: + +- Create debug and run "configurations" so you can reliably launch the application in a known state +- Create external tool "configurations" to launch the build processes and other tools + +::: info Note: + +Many of these configurations are already shared within the project. If you can't see them in the Eclipse "Debug Configurations" or "Run Configurations", its likely that your project is setup slightly differently than the way the configuration was generated. Check the "Filter launch configurations..." dialog and deselect "Filter Deleted/Unavailable Projects". All the shared configurations should then appear in the list. To use one of these, copy it and modify it to fit with your setup. Be sure to make this a local copy in the "Common" tab. This will prevent your work from being over writen. A common difference would be in the project name or if the repository is setup as a single project or multiple projects. Some of the configurations use variables such as ${adempierePropertiesFile} which will need to be set before the configuration can be run. + +::: + +#### Create Debug and Run Configurations + +Debug and Run configurations make it easy to launch ADempiere. The configurations can be created under the Eclipse "Run" menu or on the Debug/Run icon pull downs. + +The configurations need the following settings: + +Create a new Java Application configuration. +Name: Call it something specific in the case that you have multiple projects +Main Tab - Project: browse to your ADempiere project +Main Tab - Main class: org.compiere.Adempiere +Arguments Tab - VM Arguments: -Xms64m -Xmx64m -Dorg.adempiere.server.embedded=true -DPropertyFile="C:\Adempiere\Adempiere.properties" +Common Tab - Select Debug and Run in the "Display in favorites menu" + +::: info Note + +Replace the path to the Adempiere.properties files with the one you wish to use. You can also change the VM Arguments to increase or decrease the amount of memory. The VM arguments define the minimum and maximum RAM allocation for the Java VM. Check the Java documentation for more information. + +::: + +Create additional configurations for other projects as required. + +## Create External Tool Configurations + +To assist with building ADempiere and other utility functions, you can create external tool configurations that will run the Ant build targets to perform various functions. External tool configurations can be created from the Run->External Tools->External Tools Configurations... menu. Each configuration needs the following settings: + +- Select "Ant Build" and create a new launch configuration. Give the new configuration a good name like "ADempiere - build". +- Main Tab - BuildFile: ${workspace_loc:/adempiereTrunk/utils_dev/build.xml} - or wherever the utils_dev/build.xml is located. +- Build Tab - Select "Build before launch." +- Targets Tab - Select one or more targets. For the basic build, select the default, "complete". +- Common Tab - Save as local file and select Display in favorites menu - External Tools. + +Create additional configurations as required. A helpful one uses the build target "install" which will partially delete the install location and then install the ADempiere software. The "Clean" target will clean the class directories and "clean all" will perform a clean and delete the install location. Review the code utils_dev/build.xml for more details. + +There are many build files in the project that perform specific tasks. You can also create external tool configurations for these. One helpful one is in the migration directory to install migrations. For example, in the directory adempiereTrunk/migration/380lts-release/postgresql, the build.xml file can apply the long list of migration scripts from within Eclipse. You will need to copy the adempiereTrunk/migration/postgresql.properties.template file to postgresql.properties and modify it for your installation. Then create an External Tool Configuration to run the target "run-scripts". + +You can also create external tool configurations for some of the basic shell scripts in ADempiere. These are created under the external tool "Program" category. Assuming you have installed adempiere on the C:\ drive, the suggested targets are: + +- c:\adempiere\Run_Setup.bat/sh +- c:\adempiere\Run_SilentSetup.bat/sh +- c:\adempiere\utils\Run_ImportAdempiere.bat/sh + +### Compiling ADempiere + +ADempiere is configured to use two directories for each project: a src directory and a build directory. They have the same structure within each project, differing only on the file suffixes: .class for the build directory and .java for the src directory. Compiling is the process of generating the .class files from of the .java files. + +There are two ways for compiling: + +- Automatically: by default, Eclipse builds (i.e. compiles) automatically when changes occur. Project > Build is checked by default after Eclipse installation. +- Manually: in desirable cases you may want to decide when to compile (for example, when debugging the ZK software). Ensure Project > Build Automatically is not checked. You have to remember to manually compile with Eclipse before running ADempiere. + +## Building ADempiere + +Building is the process of archiving the class files into jar files and creating the installation files. Do not get confused with usage of the term "build". For Eclipse it means compiling the java files, whereas for ADempiere it is building the jar files. + +There are three ways for building: + +- Via console: open a console, change directory to /adempiere_trunk/utils_dev and run RUN_build.sh. This script performs a clean before building. You see the messages on the console. +- Via Eclipse ANT: in the navigator view, expand utils_dev and select the file build.xml. Run it via context menu (Run as > ANT Build). It is faster because it performs a build without clean. +- Via the external tool configurations created above to run the ANT build. + +Build.xml draws information from the files build.properties and properties.xml. You can also create a file mybuild.properties to override these as required. + +If you haven't installed a copy of the ADempiere client, you can do so with the ANT build as follows: + +- Copy the utils_dev/build.properties file to utils_dev/mybuild.properties or to ${user.home}/.adempiere.properties. Edit the file and change the lines according to where the installed copy of Adempiere should go. For example, to install a copy in c:\adempiere, use these lines: + +~~~ +env.ADEMPIERE_ROOT=c:/ +env.ADEMPIERE_HOME=${env.ADEMPIERE_ROOT}/Adempiere +~~~ + +- Create an external tool configuration to run the ANT target utils_dev/build.xml->install. +- Build ADempiere, if you haven't already (use your external tool or select utils_dev/build.xml and run as ANT build). +- Install ADempiere - using the external tool config created above. +- Create external tool configurations to execute programs c:\adempiere\run_setup and c:\adempiere\run_silentsetup as described above. Execute run_setup the first time and then run_silentsetup if you need to in the future. Set the parameters according to the instructions in [Application Server Installation & Setup](a). This will create several of the needed files: adempiere.properties and utils/myEnvironment.bat. + +### Database Setup + +ADempiere needs a database to function. If you haven't already installed one, follow the instructions in [Database Server Installation & Setup](a). + +Before you can run ADempiere, you will need to [Initialize the ADempiere Database](a). You do this by executing the RUN_ImportAdempiere script in the c:/adempiere/utils directory. + +::: info Note + +You can setup an external tool configuration as described above to run any of the scripts in the ADempiere installation from within Eclipse. + +::: + +## Debugging and Running the Client + +Once all the installation items are complete, debugging or running the client is as simple as selecting the proper configuration. The application should launch immediately and you can use the power of Eclipse and Java to debug and change the application. The JVM capability of hot-swapping allows changes you make in the code to affect the running instance as you save the changes. For more information on using Eclipse, see the [Eclipse documentation (Kepler)](http://help.eclipse.org/kepler/index.jsp). + +## Running and Debugging the Web Version + +See [Creating WebUI Workspace using Eclipse Webtool](./creating-webui-workspace-using-eclipse-webtool.md). + +## Debugging the Server + +To debug the server you need to be able to compile and run the client. + +Enable the debugging as follows: + +- Append the following to the line that starts with ADEMPIERE_JAVA_OPTIONS to the file utils/myEnvironment.bat|sh + +~~~ +-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8888 +~~~ + +The result will be something like: + +~~~ +@SET ADEMPIERE_JAVA_OPTIONS=-Xms64M -Xmx512M -DADEMPIERE_HOME=D:\Develop\Adempiere\stable\adempiere\Adempiere +-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8888 +~~~ + +- Start the server (using utils/RUN_Server2.sh). If you have compiled using the RUN_build.sh script mentioned in the prerequisites you'll find this script in adempiere/Adempiere/utils with the checkout directory as root). +- Use the "Attach debugger" option in your IDE. If you're using NetBeans you'll find that menu option under the main menu "Run". Attach to the server you're running ADempiere on using the specified port (in this example, port 8888). +- Add breakpoints as you please. + +## Procedures to Consider + +If you are using a production database for testing, there is no need to import the seed data. You may have to migrate your database to a version that matches the software. You can do this by applying migration scripts (see [Migration](https://wiki.adempiere.net/Migration)) or by using a Migration Tool which will compare your database against a reference and ensure that all the necessary information is added to your database. For more information, see the [Migrate](a) page. + +### First Time Use + +Before you can debug the software, you will need to generate a few of the key configuration files required by the application. Assuming you have installed all the necessary software and have Eclipse configured +properly, here are the steps: +1. Update your repository to the desired revision using your version control software. (Pick a working version for the first time - not a work in progress.) +2. Refresh Eclipse to ensure it is synced with the files in the repository following the update. +3. Copy uitls_dev/build.properties to mybuild.properties and modify to point the root to your local install directory - typically c:\ on windows machines. +4. Clean your development environment to remove old classes. +5. Build the code using the ANT build utils_dev/build.xml. +6. Install the code using the ANT install target in utils_dev/build.xml. +7. Run the RUN_Setup script in the install location (e.g. ${ADEMPIERE_HOME}/Run_Setup). For more information see Application Server Installation & Setup. +8. Copy the resulting adempiere.properties file to a safe location where it won't get overwritten inadvertently. +9. Create or modify your debug/run configurations to point the VM arguments to the copied adempiere.properties file. +10. Import the database seed (utils\Run_ImportAdempiere) +11. Apply Migrations to the seed (only if required. Migrations will be sql or xml files located in the migration\-release folder. If this folder is empty, no action is required. + 1. Apply SQL migrations - usually for versions before the 380 release. + 1. In Eclipse, copy the adempiere/migration/postgres.properties.template to postgres.properties (or the equivalent file with oracle/mysql depending on your database). Modify the file according to your +database setup. + 2. Navigate to the applicable directory in the adempiere/migration folder (e.g. adempiere/migration/370LTS-release/postgres) and run the ANT build.xml in that directory. + 2. Apply XML Migrations - after version 380LTS. Execute the debug/run configuration "Load XML Migrations". This will also apply all post migration scripts. + +After these steps you should be able to debug the application from within eclipse using a debug/run configuration. + +::: info Note + +If you rename the adempiere.properties file, you can create copies with different setup options so you can change the main options simply by selecting different debug/run configurations. + +::: + +### Major Software Update + +Following an update to your repository performed through the version control system, you will need to do the following steps, depending on the extent and nature of the change. + +::: info Note + +This procedure assumes you have all the necessary software installed and have successfully debugged ADempiere from Eclipse in the past. + +::: + +1. Refresh your development environment. +2. Clean your development environment to remove old classes. +3. Build the code - that is the ANT build discussed above. This will create the necessary library files. +4. Import the database seed and apply migrations as described above. + +After these steps you should be able to debug the application. + +## Working with a Clone from the Official ADempiere Repository + +The ADempiere Project uses a Fork and Pull model. It is best practice to fork the ADempiere repository, develop within that fork, and then have the technical team "pull" your changes into the ADempiere repository. + +This is best practice for ADempiere developers, for individuals who want to contribute or when you are working on a module/feature with a team and you commit, push, revert, merge etc. in many cycles before deciding to publish. + +The steps to do so are described in [ADempiere Version Control](https://wiki.adempiere.net/ADempiere_Version_Control) but, in summary, here the steps: + +- Go to the [Adempiere repository in Github](https://github.com/adempiere/adempiere), login with your Github account and fork from it following [these instructions](https://help.github.com/articles/fork-a-repo/). +- Go to your Github account (for example https://github.com/MY_GITHUB_ACCOUNT) and see your fork. It will be under https://github.com/MY_GITHUB_ACCOUNT/adempiere. +- Clone the ADempiere repository locally with for example git clone git@github.com:MY_GITHUB_ACCOUNT/adempiere.git or with Eclipse or your favorite IDE. +- Create a new branch for your development work. Follow the branch naming conventions in the [Software Development Procedure](https://wiki.adempiere.net/Software_Development_Procedure) - be specific. Keep your local branches limited to a single bug fix or feature development. Use as many branches as you need. +- Make some software changes and commit and push your local changes as usual and then push to your fork on github. +- When you want your changes to be submitted to the Technical Team to be accepted, follow [these instructions](https://yangsu.github.io/pull-request-tutorial) or [these instructions](https://help.github.com/articles/using-pull-requests/). Pay attention to the target branch on the ADempiere repository. +- Keeping your fork synced + - When needed, sync your fork with the ADempiere repository [as described here](http://stackoverflow.com/questions/20984802/how-can-i-keep-my-fork-in-sync-without-adding-a-separate-remote/21131381#21131381). + - You then open your local project in Eclipse and pull changes from your fork. + +## Troubleshooting + +Problems (and their solutions) that people often have when compiling ADempiere. + +- Use the proper Java version. Make sure that the JDK and JREs used in Eclipse and installed on your computer are consistent. Check the Eclipse workspace settings, project settings and build settings if you run into problems. +- On Linux systems, you have to add "execute" permission to all the shell scripts before you start! +Run the following command from the directory above the Adempiere directory to convert all shell script files. + +~~~ +find Adempiere -name *.sh -exec chmod +x "{}" \; + +Thanks to "DeathMeat" on Freenode #adempiere for that. +Notes: for OpenSuSE 10.1, it requires quote for the *.sh, which we shall type: +find Adempiere -name "*.sh" -exec chmod +x "{}" \; +~~~ + +- Errors running standard unix shell scripts +The standard unix shell scripts were created on a dos/windows platform and contain special characters that are incompatible with unix and which can cause strange errors when you run the scripts. The common dos2unix utility will correct this problem. Running the following command from the directory above the Adempiere install directory should fix this + +~~~ +find Adempiere -name *.sh -exec dos2unix -d "{}" \; +~~~ + +Thanks again to DeathMeat from freenode #adepiere for that. + +In addition to the shell scripts (i.e. *.sh files) you may also need to run this utility (dos2unix) against the file Adempiere/jboss/bin/run.conf. + +- OutOfMemoryError when running the ant build +Allow the ant Process to use more (heap) memory. One way of doing this is by setting the ANT_OPTS environment variable. Example for Windows: +set ANT_OPTS=-Xmx256M + +For many Linux system, such as OpenSuSE, Fedora, Red Hat +export ANT_OPTS=-Xmx256M + +- You may get a MailLogger Exception +MailLogger failed to send e-mail! +java.lang.Exception: Missing required parameter: MailLogger.from +Add these lines to Adempiere/utils_dev/mybuild.properties: + +MailLogger.from=username@domain.com +MailLogger.success.to=username@domain.com +MailLogger.failure.to=username@domain.com + +## See also +The interesting German version [De_DE/eclipse-setup](https://wiki.adempiere.net/De_DE/eclipse-setup) that goes right through debugging from the JBoss server. +[Hacker's guide](https://wiki.adempiere.net/Hacker%27s_guide) +[Compile](https://wiki.adempiere.net/Compile) +[Creating WebUI Workspace using Eclipse Webtool](./creating-webui-workspace-using-eclipse-webtool.md) + diff --git a/src/community/wiki/developers-guide/generating-windows-installers.md b/src/community/wiki/developers-guide/generating-windows-installers.md new file mode 100644 index 00000000000..6062b03a7a9 --- /dev/null +++ b/src/community/wiki/developers-guide/generating-windows-installers.md @@ -0,0 +1,198 @@ +--- +title: Generating Windows Installers +category: Community +star: 9 +sticky: 9 +tag: + - Wiki + - Developer's Guide + - Releasing New Versions +article: false +--- + +When a new release or update has been published, the Windows installers need to be generated to use the published binaries. This page describes how to do so. The windows installer is intended to give the a new user as simple and install experience as possible. It is not intended for production use. + +## Preparing to generate the installers +The code to generate the installers is in the ADempiere repository under the name [adempiereInstaller](https://github.com/adempiere/adempiereInstaller). + +Clone or download this repository to you local computer. You can work with the files directly or, for convenience, add the clone as a project in you development environment. + +The scripts are based on the NSIS (Nullsoft Scriptable Install System, [http://nsis.sourceforge.net](http://nsis.sourceforge.net)). and you will need this software installed on your local computer. The scripts are based on the NSIS version 3.0b2. + +The following NSIS plugins are required and must be installed: + +- [ExecDos](http://nsis.sourceforge.net/ExecDos_plug-in) +- [ShellLink](http://nsis.sourceforge.net/ShellLink_plug-in) +- [ZipDLL](http://nsis.sourceforge.net/ZipDLL_plug-in) +- [Inetc](http://nsis.sourceforge.net/Inetc_plug-in) + +There is a [NSIS plugin for Eclipse](http://eclipsensis.sourceforge.net/update) available as well which helps with editing the scripts. Read more about it at http://eclipsensis.sourceforge.net/index.shtml + +## Gathering the Necessary Files and Information + +The installers can be run to generate on-line installers which will download all the necessary files from the Internet, or off-line installers which will include all the files. The off-line installers are around 650Mb in size. + +### Off-Line Installers + +The off-line installers will need the following: + +- The contents of the ADempiere .zip file, extracted to an empty directory. Do not modify the files in anyway. The install script will include these in its own zip file. +- The Java JDK installer downloaded from Oracle. Download both the x32 and x64 versions. +- The PostgreSQL installer downloaded from EnterpriseDB. Download both the x32 and x64 versions. + +To keep the files together, it is suggested to use the following directories within the ADempiere Installer project to hold these files: + +- windows\install_scripts\tools\adempiereZip - extract the ADempiere release .zip here so you will have adempiereZip\adempiere\... +- windows\install_scripts\tools\java - include both JDK installers +- windows\install_scripts\tools\postgres - include both Postgres installers + +### On-Line Installers + +For the on-line installers, you will need the following information: + +- The URL of the published ADempiere binary .zip file. +- The URLs of the two JAVA JDK installers - the actual installer after the license has +- The URLs of the two PostgreSQL installers + +### Updating the Install Scripts + +The only file that needs to be changed is Adempiere_winx64.nsi. + +In the beginning of the file, there are a number of defines that have to be corrected. + +The following defines determine the name of the installer package. The name will be in the form ${PRODUCT_NAME}_${PRODUCT_VERSION}${PRODUCT_PATCH}_${OS_TAG}${OFF_LINE_TAG}.exe. + +~~~ +!define PRODUCT_NAME "ADempiere" +!define PRODUCT_VERSION "380LTS" +!define PRODUCT_PATCH "_2" ; Leading underscore if specifying a patch or null string +~~~ + +If there is no patch or hotfix included, set PRODUCT_PATCH to a null string "". + +Next, point SOURCE_FILE_DIR at the extracted zip location. In this case, it points to the adempiere project where the build places the files to be zipped. Access to these files is required for off-line installs as well as the installer will use the icons contained in the ADempiere project. + +~~~ +; SOURCE_FILE_DIR is the unzipped Adempiere files in the Adempiere project +; found in the install\build\Adempiere folder. This is required even if an +; on-line install is being built. The directory could also be pointed at the +; ADEMPIERE_HOME directory after a clean extract of the zipped binaries and +; before any setup has been performed. +!define SOURCE_FILE_DIR "..\..\..\adempiere\install\build\Adempiere" +~~~ + +Point the installer at the ADempiere download link and define the name of the zip file. The other defines in this section can be left as defaults. AD_SIZE is the fully installed and built size of the ADMPIERE_HOME directory. + +~~~ +; ********************************* +; Adempiere defines +; Source of web zip +!define ADEMPIERE_DOWNLOAD_LINK "https://bintray.com/artifact/download/mckayerp/ADempiere-444-Window-Install-Test/Adempiere_380LTS_2.zip" +!define ADEMPIERE_INSTALLER "Adempiere_380LTS_2.zip" +!define AD_INSTALL_DRIVE "C:" +!define ADEMPIERE_HOME "${AD_INSTALL_DRIVE}\Adempiere" +!define AD_PASSWORD "adempiere" ; Password for Adempiere installtion +!define AD_PORT "8080" ; Port used by the web server +!define AD_SSL_PORT "8443" ; Port used for SSL +!define AD_SIZE 1760000 ; The required size in kb of the AD install. Need if downloading zip. +~~~ + +For the JAVA JDK, define the name, download link URL, installer file name and the default directories for both the x32 and x64 versions. The JDK_MIN_VERSION and JDK_TARGET_VERSION defines are used to determine if the JDK install is necessary on computers that already have another JDK installed. + +~~~ +; ********************************* +; JDK defines - name of the install executable and +; the default install location +!ifdef AD_WIN32_INSTALL + !define JDK_NAME "Java JDK 1.8 Update 66 (Win x32)" + !define JDK_DOWNLOAD_LINK "http://download.oracle.com/otn-pub/java/jdk/8u66-b17/jdk-8u66-windows-i586.exe" + !define JDK_INSTALLER "jdk-8u66-windows-i586.exe" + !define JDK_DEFAULT_DIR "$PROGRAMFILES\Java\jdk1.8.0_66" + !define JAVA_HOME "$PROGRAMFILES\Java\jdk1.8.0_66" + !define JDK_SIZE 335000 ; The required size in kb of the JDK install. Need if downloading zip. +!else + !define JDK_NAME "Java JDK 1.8 Update 60 (Win x64)" + !define JDK_DOWNLOAD_LINK "http://download.oracle.com/otn-pub/java/jdk/8u60-b27/jdk-8u60-windows-x64.exe" + !define JDK_INSTALLER "jdk-8u60-windows-x64.exe" + !define JDK_DEFAULT_DIR "$PROGRAMFILES64\Java\jdk1.8.0_60" + !define JAVA_HOME "$PROGRAMFILES64\Java\jdk1.8.0_60" + !define JDK_SIZE 335000 ; The required size in kb of the JDK install. Need if downloading zip. +!endif +!define JDK_MIN_VERSION "1.7" +!define JDK_TARGET_VERSION "1.8" +~~~ + +Similar to the JDK, for Postgres, update the name, download URL, installer name, service ID and version detail of the postgres installer for both x32 and x64 installs. The other defines can be left as defaults. + +~~~ +; ********************************* +; PostgreSQL defines - name of the install executable and +; the default install location +!ifdef AD_WIN32_INSTALL + !define PG_NAME "PostgreSQL 9.4.5-1 (Win x32)" + !define PG_DOWNLOAD_LINK "http://get.enterprisedb.com/postgresql/postgresql-9.4.5-1-windows.exe" + !define PG_INSTALLER "postgresql-9.4.5-1-windows.exe" + !define PG_DEFAULT_DIR "$PROGRAMFILES\PostgreSQL\9.4" + !define PG_SERVICE_ID "postgresql-x64-9.4" + !define PG_VERSION_DETAIL "9.4.5-1" + !define PG_SIZE 465000 ; The required size in kb of the PG install. Need if downloading zip. +!else + !define PG_NAME "PostgreSQL 9.4.5-1 Win x64" + !define PG_DOWNLOAD_LINK "http://get.enterprisedb.com/postgresql/postgresql-9.4.5-1-windows-x64.exe" + !define PG_INSTALLER "postgresql-9.4.5-1-windows-x64.exe" + !define PG_DEFAULT_DIR "$PROGRAMFILES64\PostgreSQL\9.4" + !define PG_SERVICE_ID "postgresql-x64-9.4" + !define PG_VERSION_DETAIL "9.4.5-1" + !define PG_SIZE 465000 ; The required size in kb of the PG install. Need if downloading zip. +!endif +!define PG_MIN_VERSION "9.0" ; Minimun acceptable PG Version +!define PG_USER "postgres" ; Username of PG system account +!define PG_PASSWORD "postgres" ; Password for PostgreSQL installtion +!define PG_PORT "5432" ; PostgreSQL Port (5432) +~~~ + +## Generating the Installers + +### Using the NSIS Software + +- Launch the NSIS Software and click the link to "Compile NSIS scripts". +- Open and compile each of the four .nsi files to generate the four types of install scripts. + +### Using the Ant Build File + +Run the target "All", the default, in the Ant build.xml file included in the windows directory. This will generate the four installers. The xml file has other targets to generate each one or only the on-line or off-line versions. + +A launcher is included in the project to run the build from the External Tools configuration. + +Note that you may have to change the NSIS_HOME property to point to your NSIS install location. + +### Adding Languages + +The installer can support multiple languages. Currently, French and English are enabled. To setup other languages, copy the language/LangStrings_French.nsh file and rename it to the new language. Edit the file to replace the French text with your translation. The English text is in the comments. + +Be sure to set the language flag at the top of the file as shown here: + +~~~ +; Define the language + +!ifdef _LANGUAGE_ + !undef _LANGUAGE_ +!endif +!define _LANGUAGE_ ${LANG_FRENCH} +~~~ + +To include the new language file, edit the file Language.nsh and add the language to the following lines: + +~~~ +; Language files +!insertmacro MUI_LANGUAGE "English" +!insertmacro MUI_LANGUAGE "French" + +; Pending translation +;!insertmacro MUI_LANGUAGE "German" + +!include language\LangStrings_English.nsh +!include language\LangStrings_French.nsh + +;!include language\LangStrings_German.nsh +~~~ diff --git a/src/community/wiki/developers-guide/road-map.md b/src/community/wiki/developers-guide/road-map.md new file mode 100644 index 00000000000..0f7de595d53 --- /dev/null +++ b/src/community/wiki/developers-guide/road-map.md @@ -0,0 +1,53 @@ +--- +title: Road Map +category: Community +star: 9 +sticky: 9 +tag: + - Wiki + - Developer's Guide +article: false +--- + +A list of ideas and plans for future releases. + +## Big Dream Ideas + +- Common user interface approach for both client and web +- Integrated regression testing framework +- New Universal Interface based on HTML5 replacing SWING and ZK + +## Next Major Release + +- **4.0.0** +- **3.9.0** + +[Release 3.9.0 Detailed Plans](/community/wiki/preface/release_390.md) + +- Remove JBOSS and use Tomcat directly as the application server. +- Upgrade to ZK 8 +- Component tracking and component life-cycle management + +## Next Minor Release + +**3.8.3** + +- Attribute Set Instance improvements to allow text edit in fields and direct creation of serial numbers (approach needs discussion) +- Tax Engine (Now it will support Indian Tax as well as any country Tax) +- Window Customization +- PackIn - PackOut Engine + - Packaging of Rule Engine + - Packaging of Report Access Level + - Enabling of Pack-In in 380 for 370 Packout +- Jasper Reports (Report formats required by the industries) +- Do not allow to change the location & item Along with B-Partner name change after any transaction +- Inventory Raise (If Lost found/for any reason need to increase inventory) + +**3.8.2** + +**3.8.1** + +- All hotfixes to date +- Point of Sale integration +- Warehouse Management System upgrade +- Payment Selection as a document \ No newline at end of file diff --git a/src/community/wiki/developers-guide/software-development-procedure.md b/src/community/wiki/developers-guide/software-development-procedure.md new file mode 100644 index 00000000000..15b20f1e1ef --- /dev/null +++ b/src/community/wiki/developers-guide/software-development-procedure.md @@ -0,0 +1,425 @@ +--- +title: Software Development Procedure +category: Community +star: 9 +sticky: 9 +tag: + - Wiki +article: false +--- + +STATUS: This concept was accepted by the citizen by vote on 29th of November 2010. + +::: info Note + +For Developers - With the move of the repository to Github in January 2015, the project follows the "fork and pull" model of development. There is also tight integration of the Github and ADempiere issue tracker [https://github.com/adempiere/adempiere/issues](https://github.com/adempiere/adempiere/issues) using smart commits. See the Developer section for a quick overview. + +::: + +## Preface + +For quite a while, I have been participating in the ADempiere project as a committer. Throughout this time the group of developers has experienced the increasing complexity of managing this project as a mission-critical software development endeavour. + +This process has been occasionally not only complex but also tedious, since the philosophy of our project is based on the Bazaar approach, that expects many contributors with different profiles, experience and ways of thinking. So the big question is: how to manage the project with all these contributors? + +On the one hand we have contributors (aka committers) with great experience in the project. They want to and often do contribute with new features, generating a dynamic line of development. Many of these new features can be brought to our committee for approval and inclusion in the main develop branch. + +This process is very important because it lets us review and evaluate new features by experts both technical and functional. + +Another important aspect is the incredible ability of contributors to create new features, usually beginning with a creative idea that evolves and matures. After this has happened, the contributor wishes to show his deeds to others to receive feedback and eventually to submit for trial. + +The new features can be fully completed or in progress, but it is important to establish a policy of sharing functionality in order to evaluate the pros and cons of the feature. + +The process nowadays is complex because there aren't tools and procedures enabling dynamic collaboration. As a consequence of that, the project may be or seem to be stalled or still worse, these new features are never included within the main trunk, limiting the creativity and innovation of the project. + +On the other hand there are contributors who discover a problem/bug in the program. They create a solution to the problem in their private repository. In many cases, many of these bug fixes do not land in the main line of code. + +Why? In my opinion, it is because of the lack of tools and of a process that explains how to share, how to facilitate collaboration, reviews and evaluation of bug fixes in a simple way. + +Another aspect of our software development concerns the release of new versions that include bug fixes as well as new features are approved by the project committees. In the current approach, the main line of code must be frozen during the release process. This simplifies the process for the technical equipment, but has the disadvantage of stopping the momentum of a Bazaar-like project like ours, which is in constant evolution. + +The release process also involves steps towards maintaining already released versions. These versions are not fault-free and so it is possible to find errors anew. Thus the versioning process is an additional task for the technical team, and using a tool to facilitate the creation of a service pack becomes a key factor. + +Once the major issues were pinpointed, the technical committee analyzed and improved the current development process. As a result of this, changes were made in the current procedure in order to solve the current problems and thus improve collaboration in the project. + +kind regards + +[Victor Pérez](https://wiki.adempiere.net/User:Vpj-cd) + +Member of Technical Team + +## Goals + +This document is about establishing processes, rules and teams to achieve the following: + +- Produce high quality ERP software +- Regular and scheduled releases +- An all-time stable “**master**” branch +- Explicit and concise rules how to manage the ADempiere Code Repository +- Reduce overhead caused by reverts for unfinished features +- Documentation for all new features +- Teams are to be responsible not single persons +- Lean project organisation +- Continuous and reliable progress +- Increase collaboration among developers +- Facilitate the task of project management + +## Glossary + +- **Main branch** + - **master** Branch (before: stable) + - Only for release and hotfixes approved + - An infinite lifetime + +- **develop Branch** (before: development) + - Main line of code + - An infinite lifetime + - Never freezes. + - Gets voted and approved commits from features branches. + - No experiments + +- **Support Branches** (before directly in trunk) + - **Release** + - **Feature** + - **Hot Fixes** + - These branches always have a limited life time + - Since they will be removed eventually. + +![ADempiere_Repository_Structure](/assets/img/community/preface/software-development/1200px-ADempiere_Repository_Structure.png) + +## Software Production Cycle + +**Development Phase (3 Months)** + +- “develop” branch which is the main line of development. +- New functionalities are implemented in separate “feature” branches with the aim to get them into develop branch + - Developers have 3 months time for integrating new functionalities, changes, Bug fixing and Integration testing in their branch + - Before integrating new/ changed Functionality in "develop" the Developers/ Implementers have to apply for approval by Technical and Functional Team + +**Stabilization Phase (1 month)** + +- After development phase is over there is one month stabilization phase where the “release” branch is created and frozen for new features. In this time only bug fixing and User Acceptance Tests (UAT) are allowed. + +**Release** + +- When “release” branch is finished, it is integrated back into the develop and **master** branches, which are the main line of development. Eventually, a release is done using a tag. + +- The next stabilization branch cycle starts. The old branch is close. + +### Developer working in Develop Branch + +#### Responsibilities + +- Assure that code has 100% compliance with [ADempiere Best Practices (ABP)](a) +- Code is formatted using the official formatting definition (need to be defined and agreed on, but in meantime you can take this as an example) +- Respect the Distributed Version Control Best Practices (see [Committing](a)) +- Announce any data model change in order to discuss and vote it in Technical and/or Functional team (example: the placed were we store some well known data like contact phone changed) +- Announce structural changes (e.g. file, directory, rename, move, delete) should be announced and approved by Technical team before applying it +- Keep **master** Data Models (organizations, business partners, contacts, warehouses etc) consistent and do not use different ways of defining the relations between this entities (examples: storing the organization details like addresses, phones, faxes in Organization Info tab or in the linked business partner) +- In case of complex functionalities, define ADempiere Generic Workflows in order to guide the user how to setup the functionality and which is the designed the business process (example: take a look at Manufacturing Management Setup workflow from your ADempiere main menu) +- Provide necessary documentation: + - Forum post announcing the development in forum + - Wiki page (template and content to be defined) + - Feature request in tracker + - Entry in Feature Development Collaboration wiki page +- Keep his/her branch up-to-date with “**master**” branch and therefore must merge hotfixes into his/her branch. +- Provide immediate effort if the integration harms the "**master**" branch. +- Delete "dead" or "unmaintained" branches created in the past. + +#### Process + +The software development process uses a combination of workflows. For some great background on workflows, see the Atlassian article on Comparing Workflows + +The main repository at [https://github.com/adempiere/adempiere](a) is managed using a process similar to the Gitflow Workflow[1](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) in the Atlassian article. The maintenance of the main repository is the responsibility of the Maintainer. + +Developers contributing to the project use the Forking Workflow[2](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow) with the GitHub Fork and Pull model. Refer to the Github article on [Forking Projects](https://docs.github.com/es/get-started/quickstart/contributing-to-projects) for details. + +In summary: + +- The Maintainer manages the main repository [(https://github.com/adempiere/adempiere)](https://github.com/adempiere/adempiere) +- Developers should have their own account on GitHub. +- Developers fork the main repository on GitHub to their personal account `(https://github.com//adempiere)` and make a local clone of their personal fork. +- If the developer is working with Jira a lot, they should link their GitHub account with the project Jira account. This requires the help of a Jira administator so ask in the Developers forum. There is a good (if you don't mind elevator music) video tutorial on youtube showing what is involved. +- Working on their local clone, developers can open a new “feature” branch or contribute to any other branch using the Gitflow Workflow' model. +- Developers commit to their local clone and push to their fork using well documented commits. To use the smart commits that link to the Jira issues, follow the instructions on the Atlassian site. It is important to use the uppercase references (e.g. ADEMPIERE-123) in the commit messages. Read the instructions for more information. +- To have their work merged into the main repository, developers issue a pull request from their GitHub account. This will initiate a discussion with other developers, leading to the inclusion of the new work. + +::: info Note + +While the main repository will be following the branch naming very closely, developers are encouraged to use more descriptive names for their branches and to develop these "tracking" branches from a recent point on the Adempiere (origin) project. The branch should contain only the changes relevant to the pull request and the pull request should target the correct branch on the origin repository. Once the pull request has been accepted and closed the tracking branch can be deleted. (Branches in git are only pointers so deleting the branch tag leaves all the history intact.) + +::: + +### Technical Team + +Calculate 4 hours minimum work per week + +#### Responsibilities + +- Maintains “**master**” and “develop” branch +- Ensures that all contributions meet technical requirements in respect to quality: + - Code is well documented + - Backward compatibility is achieved + - Migration scripts complete + - technical documentation sufficient + - backward comparability analysis + - migration scripts are provided (when needed) +- Regular releases by providing and supporting a release manager from amongst their members + +Note: More detail in main branches section + +#### Process + +- When a contribution (either a bug fix or new feature) is ready for approval the developer submits a Pull Request on GitHub +- Technical Team meets on a regular basis and discusses the Pull Requests. The team and other developers can collaborate on the pull request if required. +- If all criteria are met the team approves the feature from a technical perspective +- The Maintainer merges the pull request into the main repository. + +Note: More detail in features branches section + +#### Actual Staff (since March 2016) + +- Victor Pérez +- Mike McKay +- Mario Calderón +- Yamel Senih +- Susanne Calderon +- Carlos Parada + +#### Release Manager + +##### Responsibilities + +- Organize contributions to keep release schedule +- Maintains release tags +- Integrate new release branch to **master** branch + +##### Process + +- Creates “release” branch from “develop” branch when new development cycle begins +- Produces a release from “develop” branch after stabilization phase +- Creates tags and merge change set into the “develop” and “**master**” branches + +Note: More detail in release branches section + +### Functional team + +Calculate 4 hours minimum work per week + +#### Responsibilities + +- Ensures that all contributions meet functional requirements in respect to quality + - Requirement is reasonable + - Feature is needed in “develop” branch or to be kept as optional extension** + - Requirement is solved + - Acceptance criteria are defined + - Test cases are complete + - User documentation is sufficient + - System documentation is sufficient + +#### Process + +- The Functional team has got the final decision on which feature is accepted and merged from “feature” branch to “develop” branch. + +#### Actual Staff (since March 2016) + +- Mike McKay +- Jatinder Kansal +- Victor Pérez +- Mario Calderón +- Eduardo López +- Yamel Senih +- Enrique Ruibal +- Colin Rooney +- Michael Judd + +### Other teams + +There are already other teams that could be integrated into this Integration Process where it makes sense. For example Usability, Security team. + +## Hotfixes + +- In exception to the Software Production Cycle there is also the possibility to apply hotfixes + +- Technical and functional team can approve that hotfixes go directly to “**master**” branch and “development” branches + +Note: More detail in Hotfix branches section + +## Service Pack + +The Technical Team agreed to maintain only one Service Pack of a former version. It would be great to support for several years (typical for this kind of applications) but our community’s resources are scarce. + +A Service Pack can be obtained by comparing the tag of the released version with the last changeset applied by a hotfix from the **master** branch. This process can be automated via a script that makes a compare and generates a patches.jar which will be applicable to the last version. + +## Reverting policy + +Technical team has the responsibility to revert code that has been committed without approval +The revert should be motivated precisely and without any doubt. +Any other person outside of the technical team (including the functional team) is not allowed to revert, but is advised to call for a revert by specifying the concrete reasons. +The revert procedure will use the repository facility that allows posts history and the reason of the revert, so a change set or commit are necessary to execute the revert. + +## Team Policy + +### Voting + +- In order to approve a contribution at least 2/3 of team members need to vote positively + +### Membership + +- Everybody can become a member of one of the teams +- The team can expel a member when one of the following applies + - member does not show up for three meetings without informing the other members in advance + - 2/3 of the team vote for expelling the member + +## Flexibility in this concept + +As there might be changes to the version control software (e.g. switching to mercurial, git) technical terms (e.g. trunk) or best practices might become obsolete. In this case the teams can advance this concept and adapt it to needs of the future. The same applies for duration of cycles that might become a subject to change. + +The only thing that the teams are not allowed to change and that is hereby voted and enforced by the citizens is + +- Features need always approval before they hit the main line of development to avoid excessively number of reverts +=> Goals "reduce overhead caused by reverts for unfinished features" and "clear rules how to get repository code " +- The aim should always be high quality of the software. If a feature is putting the quality of the adempiere to risk it should not be approved. +=> Goals "produce high quality ERP software" and "an all the time stable version" +- New features need to be applied with documentation for users and developers +=> Goal "documentation for all new features" +- The power to take decisions and organizing processes should be with teams and not single persons. +=> Goals "teams are to be responsible not single persons" and "lean project organisation" +- Team members need to dedicate a minimum amount of hours per week to the work. They need to agree on that before they become part of the team. +=> Goal "continuous and reliable progress" + +If all of above is applied we will have "regular and schedule releases". + +## The Main Branches + +![Development-Cycle](/assets/img/community/preface/software-development/Development_cycle.png) + +The central repository holds two main branches with an infinite lifetime: + +- ****master**** +- **develop** + +The **master** branch at origin should be familiar to every developer. Parallel to the **master** branch, another branch exists called **develop**. + +We consider origin/**master** to be the main branch where the source code of HEAD always reflects a production-ready state. + +We consider origin/**develop** to be the main branch where the source code of HEAD always reflects a state with the latest delivered **develop** changes for the next release. Some would call this the “integration branch”. This is where any automatic nightly builds are built from. + +When the source code in the **develop** branch reaches a stable point and is ready to be released, all of the changes should be merged back into **master** somehow and then tagged with a release number. How this is done in detail will be discussed further on. + +Therefore, each time when changes are merged back into **master**, this is a new production release by definition. We tend to be very strict at this, so that theoretically, we could use a script to automatically build and roll-out our software to our production servers everytime there was a commit on **master**. + +## Supporting branches + +Next to the **main** branches master and **develop**, our development model uses a variety of supporting branches to aid parallel development between team members, ease tracking of features, prepare for production releases and to assist in quickly fixing live production problems. Unlike the main branches, these branches always have a limited life time, since they will be removed eventually. The different types of branches we may use are: + +- Feature branches +- Release branches +- Hotfix branches + +Each of these branches have a specific purpose and are bound to strict rules as to which branches may be their originating branch and which branches must be their merge targets. We will walk through them in a minute. + +By no means are these branches “special” from a technical perspective. The branch types are categorized by how we use them. They are of course plain old Mercurial branches. + +### Feature branches + +- May branch off from: **develop** +- Must merge back into: **develop** + +Branch naming convention: anything except master, develop,release-*, or hotfix-* + +Feature branches (or sometimes called topic branches) are used to development new features for the upcoming or a distant future release. When starting development of a feature, the target release in which this feature will be incorporated may well be unknown at that point. The essence of a feature branch is that it exists as long as the feature is in development, but will eventually be merged back into **develop** (to definitely add the new feature to the upcoming release) or discarded (in case of a disappointing experiment). + +Feature branches typically exist in developer repository only, not in origin. + +#### Creating a feature branch + +##### Incorporating a finished feature on develop + +Finished features may be merged into the **develop** branch definitely add them to the upcoming release. + +##### Release branches + +- May branch off from: develop +- Must merge back into: develop and master' +- Branch naming convention: release-* + +Release branches support preparation of a new production release. They allow for last-minute dotting of i’s and crossing t’s. Furthermore, they allow for minor bug fixes and preparing meta-data for a release (version number, build dates, etc.). By doing all of this work on a release branch, the development branch is cleared to receive features for the next big release. + +The key moment to branch off a new release branch from develop is when development (almost) reflects the desired state of the new release. At least all features that are targeted for the release-to-be-built must be merged in to develop at this point in time. All features targeted at future releases may not—they must wait until after the release branch is branched off. + +It is exactly at the start of a release branch that the upcoming release gets assigned a version number—not any earlier. Up until that moment, the development branch reflected changes for the “next release”, but it is unclear whether that “next release” will eventually become 3.6 or 4.0, until the release branch is started. That decision is made on the start of the release branch and is carried out by the project’s rules on version number bumping. + +##### Creating a release branch + +Release branches are created from the develop branch. For example, say version 1.1.5 is the current production release and we have a big release coming up. The state of develop is ready for the “next release” and we have decided that this will become version 1.2 (rather than 1.1.6 or 2.0). So we branch off and give the release branch a name reflecting the new version number. + +After creating a new branch and switching to it, we bump the version number. Here, bump-version.sh is a fictional shell script that changes some files in the working copy to reflect the new version. (This can of course be a manual change—the point being that some files change.) Then, the bumped version number is committed. + +This new branch may exist there for a while, until the release may be rolled out definitely. During that time, bug fixes may be applied in this branch (rather than on the develop branch). Adding large new features here is strictly prohibited. They must be merged into develop, and therefore, wait for the next big release. + +##### Finishing a release branch + +When the state of the release branch is ready to become a real release, some actions need to be carried out. First, the release branch is merged into master (since every commit on master is a new release by definition, remember). Next, that commit on master must be tagged for easy future reference to this historical version. Finally, the changes made on the release branch need to be merged back into development, so that future releases also contain these bug fixes. + +Now we are really done and the release branch may be removed, since we don’t need it anymore: + +##### Hotfix branches + +Hotfix branches are created from the master branch. For example, say version 1.2 is the current production release running live and causing troubles due to a severe bug. But changes on develop are yet in process. We may then branch off a hotfix branch and start fixing the problem. + +Don’t forget to bump the version number after branching off! Then, fix the bug and commit the fix in one or more separate commits. + +##### Finishing a hotfix branch + +When finished, the bugfix needs to be merged back into master, but also needs to be merged back into develop, in order to safeguard that the bugfix is included in the next release as well. This is completely similar to how release branches are finished. First, update master and tag the release. + +The one exception to the rule here is that, when a release branch currently exists, the hotfix changes need to be merged into that release branch, instead of 'develop branch. + +Back-merging the bugfix into the release branch will eventually result in the bugfix being merged into develop too, when the release branch is finished. (If work in develop immediately requires this bugfix and cannot wait for the release branch to be finished, you may safely merge the bugfix into develop now already as well.) + +Finally, remove the temporary branch. + +## Testing ADempiere + +ADempiere is tested by a team of volunteers at each major release. + +Automated testing of ADempiere is also performed using test scripts that cover the critical functions. For more information, refer to [Adempiere Automated Testing](a). + +## Integrating Bug Fixes + +See [managing pull requests](https://docs.github.com/es/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests), [pull requests tutorial](https://yangsu.github.io/pull-request-tutorial/) and [What Is A Pull Request](http://oss-watch.ac.uk/resources/pullrequest). + +If you want to fix a bug you can do it two ways + +- if you are an ADempiere developer, you have tested your code thoroughly and you are sure of what you've done: just do the commit and the push in the corresponding branch after consulting the Technical and Functional Team. +This is described below. + +1. Open a console or terminal. +2. Create a backup for example with the command cp adempiereSource adempiere.bak +3. Go to the sources for example with cd adempiereSource +4. Execute git pull +5. Execute git checkout hotfix/3.8.0#002. This is because you want the bug fix applies to this very branch. If there is another branch you want the bug fix to be applied, just modify the checkout command accordingly. +6. Do changes and modifications towards bug fixing in the branch (in our case hotfix/3.8.0#002). +7. Execute git commit -m 'my comments to the bug fixing, with reference to the altlassian/github site were the bug was created' +8. Execute git push +9. In the github Adempiere page you can create a pull request for this commit. This pull request can be used in other branches. +10. For new hotfixes, all patches will be collected and tested, and a collection of all patches (patches.jar) will be created for the branch. contribute. + +- if you are not an ADempiere developer or you are an ADempiere developer, but you don't want to commit nor push it directly because you want others to check it before committing and pushing: + +1. you must create a branch where you want do the bug fix. +2. do the modifications there +3. create a pull request in your branch. +4. Your pull request can be used in other branches + +This is an effective ans easy way of collaboration, where developers and non-developers can contribute. + +## Bibliography + +- [A successful Git branching model](http://nvie.com/posts/a-successful-git-branching-model/) +- [Git cheetsheet](http://www.globallinuxsecurity.pro/static/git/cheetsheet.pdf) +- [GitHub Forking Projects](https://guides.github.com/activities/forking/) +- [Atlassian Comparison of Software Development Workflows](https://www.atlassian.com/git/tutorials/comparing-workflows) +- [A youtube video on using the Jira DVCS connector](https://www.youtube.com/watch?v=SCNWWfXpCw0) +- [GitHub introduction to the Flow model which describes the Pull Requests](https://guides.github.com/introduction/flow/) \ No newline at end of file diff --git a/src/community/wiki/developers-guide/software-testing-and-qa.md b/src/community/wiki/developers-guide/software-testing-and-qa.md new file mode 100644 index 00000000000..5b39f4084a7 --- /dev/null +++ b/src/community/wiki/developers-guide/software-testing-and-qa.md @@ -0,0 +1,42 @@ +--- +title: Software Testing and QA +category: Community +star: 9 +sticky: 9 +tag: + - Wiki + - Developer's Guide +article: false +--- + +## Software Test Strategy + +While it is likely impossible to fully test a complex application such as ADempiere, software testing can be used effectively to demonstrate the quality of key functionality and ensure new features meet their functional specifications while ensuring backwards compatibility. + +As testing is an often onerous and tedious task, finding ways to simplify test creation and automating the test execution is critical to an open source project. If it is easy, there is a greater chance that many developers will be able to collaborate in the development and maintenance of the tests. + +The tests should be part of the nightly build process where changes to the development branch can be tested against their functional specs, providing rapid feedback to developers who are actively working on new features and bug fixes. The tests should also be available to developers so that they can be run locally before major commits to the Source Forge repositories. + +Goals: + +- Testing of major processes in the application with the aim of testing all models +- Testing of the GUI/Webui functionality +- Testing of all new features added following Release 3.70LTS +- Verification of identified bugs and bug fixes + +## Software Test Tools + +- [JUnit](https://wiki.adempiere.net/Adempiere_Junit_test) +- [UISpec4j](https://wiki.adempiere.net/index.php?title=ADempiere_Testing_with_UISpec4j&action=edit&redlink=1) +- [Sahi](https://wiki.adempiere.net/ADempiere_Testing_with_Sahi) +- [Fitnesse](https://wiki.adempiere.net/index.php?title=ADempiere_Testing_with_Fitnesse&action=edit&redlink=1) +- [ApacheBench](https://wiki.adempiere.net/ADempiere_Testing_with_ApacheBench) + +## Functional Tests + +Generic functional tests will be completed for each nightly build. The functional tests are outlined in the page [Functional Tests](https://wiki.adempiere.net/Functional_Tests). + +## Test Process + +- Test development +- Test execution and reporting diff --git a/src/community/wiki/developers-guide/steps-to-release.md b/src/community/wiki/developers-guide/steps-to-release.md new file mode 100644 index 00000000000..556564ae4c9 --- /dev/null +++ b/src/community/wiki/developers-guide/steps-to-release.md @@ -0,0 +1,54 @@ +--- +title: Steps to Release +category: Community +star: 9 +sticky: 9 +tag: + - Wiki + - Developer's Guide + - Releasing New Versions +article: false +--- + +Archive for versions 3.3.0 through 3.5.2a [Steps_To_Release_Archive](https://wiki.adempiere.net/Steps_To_Release_Archive) + +Archive for versions 3.4.2s through 3.6.0LTS [Steps_To_Release_Archive2](https://wiki.adempiere.net/Steps_To_Release_Archive2) + +To Do | Done By +-- | -- +Release Version | [3.8.0LTS](https://wiki.adempiere.net/Release_380LTS) +Target Date | 2013/10/14 +Release Date | 2015/01/01 +Prepare wiki release from svn log.Sample [Release_320](https://wiki.adempiere.net/Release_320) | Done [Release 380LTS](https://wiki.adempiere.net/Release_380LTS) +Change sources to point new versionbase/src/org/compiere/Adempiere.javalaunch/Adempiere.xmlserverRoot/src/web/adempiere.htmlserverRoot/src/web/adempiere.jnlputils/adempiereDirectTemplate.jnlputils_dev/build.properties | 7141, 7817, 8039 +Create new postgres seedFresh build & installRUN_ImportAdempiereRUN_MigrationXMLRUN_ExportReferencejar the Adempiere_pg.dmp and Adempiere.log into Adempiere_pg.jarupload Adempiere_pg.jar seed into release/data/seed | pending +Create the new oracle seedFresh build & installRUN_ImportAdempiereRUN_MigrationXMLRUN_ExportReferencejar the Adempiere.dmp and Adempiere.log into Adempiere.jarupload Adempiere.jar seed into release/data/seedNOTE: This could also be done using the migration tool to copy the postgres seed to oracle | pending +Upload Reference databases to Source Forge | pending +Change and compile new Launch4j | 8040 +Generate complete model for new version (core and e-evolution) (be careful not to include customizations)To realize which package and where to put the generated classes execute the following querySELECT DISTINCT e.entitytype, COALESCE(e.modelpackage, 'org.compiere.model')FROM ad_entitytype e, ad_table tWHERE t.entitytype = e.entitytypeORDER BY 1 | pending +Rename current-release (i.e. 320-release) to current-next (i.e. 320-330) | Done +Create directory next-release (i.e. 330-release) | Done +HG Flow finish feature for the release branch and merge with development/master | pending +Apply tag to the release revision in the master branch | pending +Create new release package | pending +Compile the new version to make installer (RUN_build) | pending +Test an installation with the installerTest the installTest the webstoreTest the client | pending +Upload to sourceforge as current release (all, including MD5) | pending +Edit english and spanish wikipedia pagesen wikipedia Adempierees wikipedia AdempiereComparison of accounting software (if LTS) | pending +Edit other languages wikipedia pageRomânaDeutschFrançais??? |   +Prepare a new AVARed1 (Howto Create AVA) |   +Prepare new windows installer |   +Update Live Demos | pending +Update Daily Build |   +Edit freshmeat (advise to Sempre)Currently administered by semprehttp://freshmeat.net/projects/adempiere |   +Press release | pending +Change wiki [Template:LASTRELEASE](https://wiki.adempiere.net/Template:LASTRELEASE) |   +Upload wiki manuals (for LTS versions) | pending +Upload wiki screenshots (for LTS versions) |   +[Update javadoc ](http://www.adempiere.com/javadoc/) |   +[Update schemaspy](http://www.adempiere.com/schemaspy/) | pending +(desirable) update db/ddlutils model and data following instructions from [Migration/DDLUtils](https://wiki.adempiere.net/Migration/DDLUtils) -f build-ddl.xml writeSchemaToFileant -f build-ddl.xml splitSchemaFileByTableant -f build-ddl.xml writeDataToFileant -f build-ddl.xml splitDataFileByTable | (Needed with the migration tool?) + +## See Also + +- [Steps To Release HowTo](https://wiki.adempiere.net/Steps_To_Release_HowTo) \ No newline at end of file diff --git a/src/community/wiki/preface/joining-the-adempiere-community/README.md b/src/community/wiki/preface/joining-the-adempiere-community/README.md index dd73085756c..fdb62e5c982 100644 --- a/src/community/wiki/preface/joining-the-adempiere-community/README.md +++ b/src/community/wiki/preface/joining-the-adempiere-community/README.md @@ -11,7 +11,7 @@ article: false If you are reading this, you are already part of our community. -ADempiere is a open-source project using [commons-based peer-production](https://en.wikipedia.org/wiki/Commons-based_peer_production) methods. Organized as a bazaar of [Citizens](../citizens/README.md), the project is governed by [Technical](a), [Functional](a) and [Community Council Teams](../community-council-team/README.md). The intellectual property of the community is protected by the ADempiere Foundation, a non-profit group which provides legal and financial support to the community. +ADempiere is a open-source project using [commons-based peer-production](https://en.wikipedia.org/wiki/Commons-based_peer_production) methods. Organized as a bazaar of [Citizens](/community/citizens/README.md), the project is governed by [Technical](a), [Functional](a) and [Community Council Teams](/community/community-council-team/README.md). The intellectual property of the community is protected by the ADempiere Foundation, a non-profit group which provides legal and financial support to the community. The project follows a Open Source philosophy with a 3-line principle of: @@ -22,11 +22,11 @@ The project follows a Open Source philosophy with a 3-line principle of: To join our efforts all you have to do is get involved. - Learn - - Adopt our [Etiquette](../preface/quality-assurance-and-problem-reporting-guidelines/the-etiquette-of-involvement.md) and learn about our [Community Governance Structure](../community-council-team/community-governance.md) and, specifically, our [Behaviour Guidelines](../community-council-team/community-governance.md). + - Adopt our [Etiquette](/community/wiki/preface/quality-assurance-and-problem-reporting-guidelines/the-etiquette-of-involvement.md) and learn about our [Community Governance Structure](/community/community-council-team/community-governance.md) and, specifically, our [Behaviour Guidelines](/community/community-council-team/community-governance.md). - Read this wiki - - Read [Getting Involved in QA](./quality-assurance-and-problem-reporting-guidelines/getting-involved-in-qa.md) + - Read [Getting Involved in QA](/community/wiki/preface/quality-assurance-and-problem-reporting-guidelines/getting-involved-in-qa.md) - Connect