We Welcome GitHub Pull Requests

Thank you for contributing to coreBOS Open Source project!

coreBOS is a git based open source project. That means that contributing to the project is basically the same as for any other git based project. The workflow applied is Forking Workflow.

There are a dozen concepts you need to know to get your head around the initial learning curve.

To setup a development install for coreBOS you will need to take these steps

• fork the project on GitHub
• clone your fork on your local development computer
• set the permissions on the files so your user is the owner of all files (so you can edit them normally with your user) and the webserver user is the group (so it can write the files it needs to write to work)
• install the project as you would normally
• once you can log in, drop to the command line (I am assuming Linux here)
• move the renamed install directory and file back to their original place: the directory “install” and the file “install.php” will be renamed after the installation is complete to something like 8432658395801x3fab13af3.42704102intall“ for security reasons. Rename them back to their original name
• launch git status you should get only three changes tabdata.php, config.inc.php and test/vtlib/HTML/README.txt file that was deleted. I usually leave it at that, those four are always there and I just ignore them. You can recover the deleted file (git checkout test/vtlib/HTML/README.txt) if you want to only see the config.inc.php and tabdata.php files.

Now you are ready to start developing but first some other it comments:

If you see many more files changed it is because git is controlling the files permissions changes and you probably have some differences, these are not important so configure your git to ignore file permissions with this command

git config --global core.fileMode false

You can also check that the only change on the file is the permissions with

git diff filename

and then undo the change with

git checkout filename

Another few git configuration changes that come in handy are

git config --global user.email "bob@example.com"

git config --global user.name "bob example"

git config merge.renameLimit 999999

Now that you can launch a git status and see only the four files indicated above or less we can start the contribution process.

For every change you want to implement you start from the master branch, which is the default branch, you create a new branch, develop want you need, with as many commits and time as you need, when you have it finished, tested and all committed you push it to gihub.

Now go to GitHub and you will see the option to create a Pull Request from your branch. I will get notified, I will study your changes, comment, maybe ask you to make some more changes for which you will need to checkout your branch again and add them there, when you push them, GitHub will update the PR. I will finally accept your changes and incorporate them to the main master branch.

Once that happens you update your fork and your master branch gets the changes so your branch is not needed anymore and you can delete it.

Then you start all over again.

Let's see that explanation in git commands. Let's suppose I have a coreBOS fork on https://github.com/joebordes/corebos and I want to develop a new feature. That would look something like this:

cd /var/www
git clone https://github.com/joebordes/corebos cbjoebordes
chgrp -R www-data cbjoebordes
> Install coreBOS
mv 123456789.install install
mv 123456789.install.php install.php
git checkout -b new_feature
> Develop and test here
git push
git checkout master
> Wait for approval
> I ask for some additional adjustments
git checkout new_feature
> Make change and commit
git push
git checkout master
> I accept your change
git pull upstream master
git branch -d new_feature
> Start all over again

Obviously you can have as many branches as you need at the same time, developing many features in parallel.

If you need to update your branch with the latest changes from the main stream master branch you would launch a merge command. When you launch the git branch -b command to create a new branch that branch starts from the state the master branch is in at that moment. Let's suppose that it takes you a few days to finish your feature and in that time coreBOS has added a few more commits. You need to add these changes to your branch before pushing, to do that we would execute:

git checkout master (just to make sure)
git pull upstream master  (we get the new changes)
git checkout new_feature
git merge master
> Fix conflicts if any appear

The new commits are now also in your branch

When doing the pull and merge it is possible that you run into some conflicts. That means that you are changing a file that has changed in the main repository. It is your responsibility to fix that, because you are the one who knows what your changes are about. To make this process easier git has a syntax that helps you, but I usually configure merge tool with meld like this

git config --global merge.tool meld

which gives me a nice graphical interface to resolve conflicts.

I would recommend you put all your installs under git control, that way moving changes around and keeping them all up to date is extremely easy. For example, let's suppose that I get a new project, a client that wants to make some changes to coreBOS for their particular needs. I Will create a new git repository for them, I will merge in the latest version of coreBOS, at that point my local clone of their repository has two remote repositories, their private repository, and the GitHub upstream open source project. I start developing and find an error in coreBOS or I see a feature that should be available for everybody, I can cherry-pick the relevant commits or simply develop the changes directly in the open source project and then pull them in to the private repository, this is all just as simple as the workflow I explained above about branching and pull request.

But even more, when this client starts working with coreBOS, after a few weeks he runs into an error that we have already fixed in the mainstream, it is just as easy to upgrade their private repository with a pull as we did above to update the master branch. Incredibly powerful!

These two files are different on almost all coreBOS installs. They start (mostly) empty on the main repository and get modified when you install the application and when you install or deactivate modules. These changes are specific to each install, so if we make any modification to them we will be causing git merge conflicts for everyone and those conflicts will mostly be resolved by keeping their particular version. Ideally, we could have not included them in the distribution but it is too late for that now.

The recommended procedure to manage these files is to version them in the main repository of the install. As recommended above, each coreBOS install should have its own repository and pull in changes from the main coreBOS repository. So you will version the config.inc.php and tabdata.php files in the repository of the install. This way you have these important files controlled for each install and coreBOS main repository will not modify them. If you install a new module, your tabdata will change and you can commit it to the local repository. Obviously, this repository should not be publically accessible.

Now this brings us to one problem. When a developer who needs to work on the project clones the install locally they need to modify config.inc.php to adapt it to their development environment, this requires modifying config.inc.php and could lead to a mistake where you commit the file and break the production installation. To avoid this, config.inc.php includes the file config-dev.inc.php at the end of the script. This file is ignored by the .gitignore file so it will never be committed and will only be on each local development machine that needs it. This file will permit us to override any settings in config.inc.php without having to modify that file.

The config-dev.inc.php template I use is this one:

<?php
error_reporting(E_ALL);
ini_set('display_errors', 'on');
$site_URL = 'http://localhost/coreBOSwork';
 
// root directory path
$root_directory = __DIR__.'/';
 
$dbconfig['db_name'] = 'database name';
$dbconfig['db_username'] = 'database user';
$dbconfig['db_password'] = 'database password';
 
$dbconfig['db_server'] = 'localhost';
$dbconfig['db_hostname'] = $dbconfig['db_server'].$dbconfig['db_port'];
$hostname=$dbconfig['db_hostname'];
$LOG4PHP_DEBUG = true;
//$default_language = 'en_us';
?>

Another situation that appears from time to time is when you don't have a private repository for your install, you just clone the main repository from GitHub, install it, and work there. In this case, both config.inc.php and tabdata.php appear in the “git status” commands and are always there as you can't commit them. You have two alternatives:

• one is just ignoring them, it really isn't that much noise and you get used to seeing them there
• the other is to tell git to not show them to you with the command:

  git update-index --skip-worktree config.inc.php tabdata.php

Git is much more complex and flexible than what I explain here, but in the end you usually use the same commands over and over. I still recommend dedicating time to studying git but take your time one step at a time, let the concepts sink in it is really a very powerful tool.

There is a lot of documentation and examples on the internet so look there for guidance and also join our gitter group where we have close and quick chats about development

I look forward to seeing your code!

• Fill out a Contributor License Agreement. If your contribution is happening on behalf of a company, they should sign a Corporate Contributor License Agreement
• Please complete, sign the form, scan it and send it to us via email
• We'll process it, and send you an introduction email.
• You'll then appear as a approved contributor, and be upgraded to a Developer on the Ticket Tracking System: allowing you to modify and transition ticket status.

• I thought I understood Open Source. I was wrong
• Effective Ways to Get Help from Maintainers