This is an old revision of the document!
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 "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 repository, 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 work flow I explained above about branching and pull request.
But even more, when this clients starts working with coreBOS, after a few weeks he runs in to an error that we have already fixed in the main stream, it is just as easy to upgrade their private repository with a pull as we did above to update the master branch. Incredibly powerful!
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.