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
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 "firstname.lastname@example.org"
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 must NEVER be in any commit you make on the main project. I will not accept any pull request that contains any modifications to these files.
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:
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!
We'll test, verify and merge your changes and then close the Pull Request, or get back to you with any comments we may have. Please be patient, our resources are limited.
We aren't doing this due to the small amount of contributors we have. We SHOULD be doing it though.