This page shall help you getting your own ADempiere Repository fork up and running.
For a beginning have a look at https://bitbucket.org/CarlosRuiz_globalqss/adempiere361 You see the main developer Repository of Carlos Ruiz. In a decentralized development model (using a DVCS, a distributed version control system) everyone has his own repository. There is no "main" branch. But there are people that trust each other and exchange code regularly. And there are people which are trusted by many others because of the merits they earned in the past. One of them is Carlos Ruiz so beginning with his Repository is a good idea.
On the bitbucket page you see that you can download the Repository with
But what if you want to change something in the ADempiere core and want to contribute these changes back? The ADempiere development model supports you by giving you the opportunity to build your own fork. You can point others to this fork and let them extract your patches without being afraid whether your code is "good enough".
create a bitbucket account
First you should click on login on the bitbucket page and then choose to sign on for a free account. (There are commercial bitbucket plans but you do not need them for a open source project).
you should answer all the questions and reply to the confirmation email. That's it.
create a fork
At next you want to fork another Repository (for example the globalqss361 fork). You may read the [bitbucket documentation]. In short: You go to the well known site https://bitbucket.org/CarlosRuiz_globalqss/adempiere361 and press the "fork" link (with the blue arrow icon).
You may change the Name (I extended it with my initials to tag it as my own variation) and give it a Description. After pressing the "fork" button it takes some time to copy the repository (the ADempiere source repo is quite big...).
As you see I am only allowed to create a non-public repository. This is because at this time Carlos Ruiz configured his main repo to not let me do this. It is changed in the meantime and you should make your repo public to share your work easier.
use this fork
You can use this Repo like the original one. See my own fork at https://bitbucket.org/tbayen/adempiere361-tb. The command to clone it via http or via ssh is written on the overview page. You may use
hg clone ssh://email@example.com/tbayen/adempiere361-tb
The best way is to install the [Eclipse Mercurial Plugin] and to create a new project as a Mercurial Clone of "ssh://firstname.lastname@example.org/tbayen/adempiere361-tb".
If you have an already cloned Repository you probably do not want to clone it again (downloading 1GB of data again). You can use every repository you have at your home and synchronize it with your new created fork (this is *distributed* isn't it?) As far as I know you can configure the default push/pull repository in a config file inside the .hg directory. I use the Eclipse Mercurial plugin. I open the project preferences, tab page "Mercurial" and "Add..." a new Repository:
The username for the Mercurial Connection is "hg". Your Bitbucket username is part of the URL you use. This is a bit confusing but exactly this connection string is written on your overview page.
Now you can use this fork as expected: You make changes (inside Eclipse), then commit them to your local repository and can push them to your bitbuckewt repository. There you can make a pull request to your "mother" repository's owner or you may let some other people have direct access to your repository to check your patches, make them even better, spread them and make the world a better place... :-)
To learn how to contribute bugfixes and change the core please read ahead at ADempiereDevelopmentEntry.
keep the fork synchronized with the master
Now you want to keep your fork up to date with the master. What does that mean?!? My first thought was to search a button for some automatic process that synchronizes my fork every night. I really like scripts that do such annoying daily tasks. But that won't work. :-( In a distributed VCS every changeset has the risk of a merge conflict. So it is always a better idea to do it manually. And manually means you can't do it on the bitbucket server. This server does not have the right tools to merge conflicts. Why? The question should be: What is the right tool? For me the right tool to merge conflicts is my own development environment. I did my own code in this environment and if some merge tool tells me there is something strange happening to my code I want to use my own environment to deal with the problem. So the consequende is that merging always has to be done on your local system in your local environment. Later you have to bring the new changesets from your local repository into the bitbucket fork.
How do we do this? On bitbucket, you can press the "compare fork" button to compare your fork with the master. Please switch to the view of the incoming changes. When you did this you see a frame with some Mercurial commands to synchronize your local repository with the master fork. It is like this:
hg pull -r globalqss_adempiere361 https://bitbucket.org/CarlosRuiz_globalqss/adempiere361 hg update globalqss_adempiere361 hg merge 45f441bfae13
(The ID in the merge command is the ID of your actual changeset and will not be the same in your case).
This commands work on the command line and describe what happens: You get the news from the master fork, you update to the top of this fork and you merge your own changes into it. If there are conflicts read the [mercurial documentation] how to resolve the conflict. I want to extend this commands with another to confirm the merge:
hg commit -m merging
Read the [mercurial documentation] if you are not familiar with merging.
Now it is time to upload the new state to your bitbucket repository:
hg push ssh://email@example.com/tbayen/adempiere361-tb
With a right-click on the project entry in the Package Explorer I open the context menu and choose "Team -> Pull...". As URL I enter "https://bitbucket.org/CarlosRuiz_globalqss/adempiere361" (if is is not already choosen, you can set the default repository in the project preferences on the "Team" page).
The workflow is like above (I like the clearness of the command line): pull -> update -> merge -> commit. So you can have a checkmark at "Update after pull" and "Merge and, if there are no conflicts, commit after update". You may even choose to do these steps manually from the context menu.
With this you can upgrade to the actual master version with two clicks. Next you can choose "Team -> Push..." and enter something like "ssh://bitbucket.org/tbayen/adempiere361-tb" (ssh-URL without "hg@") as URL and "hg" as username (yes, this is how it works!) to upload the changes to your own bitbucket repository. That's it. You may control your deeds on your bitbucket webpage. You will see notifies about the newly uploaded changesets from the master and your merge commit.
how to do a contribution
Do I still have to explain that? The very first is to identify the problem. Use the bugtracker at http://jira.idempiere.com for that. Writing a good jira ticket is not the domain of this article. Ask if you are unsure. Else just do it and see what others tell you. Go to IRC and tell others what you want to do. Trust to peer review.
Before doing your own work you should first synchronize with the master. (The less differences with the master the easier it will be to merge your change.) The you do your work. If you feel it is worth uploading you do a commit. Use the jira-ID and -Description for the commit message. The do a push.
There is a nice Article with Screenshots about Bitbucket Commit and Pull-Request from Nicolas Micaud.
Thoughts about Branching and Changeset Policy
Note: This section is about something I do not know much of. Just some thoughts...
It may be a good idea to begin an own branch in your repository for your own work. If not you may run into a bit of trouble when the master maintainer will not accept your contribution. I will have to research this further when I got more experience with this. (Tell me if you are know more!)
Personally I do many commits until my work is ready ([commit often paradigm). But probably I do not want every small typo as his own commit into the adempiere tree. I wonder if one can pack some commits together or if I will use two repositories: One for my internal development (many commits) and one for the outside world (one commit per jira issue). How do I copy my work from one to the other?!?
contribute database changes
If your contribution needs a change in the Application Dictionary you have to add a migration script to your Repository. The secret is first to create migration scripts and second to save them in the right place an give them the right name.
The best way to begin is to use a clean database, turn the SQL recorder of ADempiere on an do your change inside of ADempiere. You can do this also directly as SQL code but this seems to me more difficult to avoid mistakes and typos. And you have to create SQL scripts both for Oracle and PostgreSQL. See how to automatically create migration scripts at [Generating Migration Scripts].
If you did this you should have alook into the "migration" directory of your trunk. Inside are directories for every adempiere release. Choose the latest directory (today it is "360lts.010-release" - it may be a convention that it ends with "-release"). Inside this you see a postgresql and a oracle directory. There you see the migration scripts. Find the one with the highest number (synchronize your repository with the master before!). Then you should create a new migration script following the naming convention you see:
<number>_<jiraID>_<jiraDescription>.sql. You may copy your automatic created scripts (you find them in "/tmp" under Linux) as a starting point. Do not forget to create one postgresql and one oracle script!
No you should be fast and contribute the script to the master before another guy chooses the same script number. :-)
If you want to deal with the scripts of other people and read more about migration scripts you may want to learn about the [Migration Script Manager].
how to submit your contribution to the master
If you are sure your contribution is ready you may
- show others the link to your repository (https://bitbucket.org/tbayen/adempiere361-tb).
- extract a patch from your contribution (see documentation of "hg patch").
- You can add this patch as a file to the jira tracker
- You can send this patch to a maintainer of the master branch for insertion
- use the "create pull request" button to inform the master maintainer. He may accept your changes into his fork
If you have further notes or want to have write privileges for this wiki to help me please contact Thomas "tbayen" Bayen at tbayen - at - bayen.de.