During the last few weeks, coreBOS has seen some new developers arrive to the project and some long time adept start collaborating more frequently so I thought it was time to set in writing the rules and guidelines we try to follow in this project. This idea has been floating around my head for a long time as I dedicate a lot of time to formatting and validating code changes and pull requests for the project. I strongly recommend that all developers that wish to help out read these guidelines and try to adhere to them as much as possible, but don't worry, I'll still be here to impose them :-)

At coreBOS, we base a lot of our open source project directives based on the wonderful work done by Karl Fogel in his book Producing Open Source Software. So, I mostly followed his recommendations when creating the coreBOS Development Guidelines.

You can find the full set of rules on our documentation site, but let's go over the main rules.

Where to speak with other developers and look for help

This one is easy: Gitter!!

Come on over and join the conversation, we are a really friendly and helpful community.

How to Contribute and Report Bugs

coreBOS is an open source project that is managed in git on GitHub, so the best way to collaborate is to follow the forking workflow and use GitHub Issue Section to report bugs.

Contact me if you need help.

Code Formatting and Structure

Here we have a set of rules that is an adaption of the PHP-FIG Standards Recommendations.

On our development guidelines page I mostly try to indicate the parts where we are not aligned with them. Those points aren't many and you will be mostly correct if you follow their recommendations, so you MUST read the PHP-FIG guidelines. The few places we diverge are due to my personal preferences and the reality of the code base we have inherited.

Keep in mind that I like compact code, reduce empty lines and tabs instead of spaces

Error Reporting and MySQL Strict

All development MUST be done using error_reporting set to E_ALL and MySQL set to Strict Mode.

This is REALLY important. We have undergone a big effort to eliminate all the warnings and notice messages in the code to enable our developers to work in E_ALL mode and for our users to be able to install coreBOS in MySQL Strict mode.

This helps the programmer avoid errors and create more compatible and error resistant code. For example, during the elimination process I fixed some errors as you can see here:

This also reduces the strain on the server as PHP does not have to trigger the warnings, which also impacts performance.

If you run into any part of the code that has a lot of warnings let me know and I will attend.

Note that production installs must use E_ERROR.

Security

Security is hard. It is a very complex and important issue which requires a lot of dedication and time. There is no way around it except studying and understanding security issues.

Reserve time for it, read, learn and apply. Iterate. Constantly.

Talk to us about it, share your findings.

Commit Guidelines

We try to follow the AngularJS Conventions for commit messages. Besides that it is important to follow a few steps before emitting a commit:

  • eliminate debug messages
  • pass a lint process or, at least, launch a syntax validation on the files (php -l)
  • make as many commits as you need to ensure concise and cohesively related changes (the git "-p" directive is your friend)

Welcome to the coreBOS Development process!!


  • Become a Patron!

Next Post Previous Post