The documentation is a little sparse around how to setup and maintain a development environment for working on LibreTime. Contributing outlines git and social issues, but it doesn’t cover required packages for installing a development system or suggested testing methods.
I don’t mind writing these up in a form welcoming to new people, but I need some pointers as to what is the current way of setting the development environment up, and building and testing the subsequent changes. Does anyone have any suggestions?
Xdebug is one package I’ve found useful in terms of debugging. I started to write some notes on how to install it but we might want to install it by default with vagrant.
In terms of testing, we have very little guidelines and have been very lack in terms of coverage because the coverage for the existing code base was so sparse. It’s not a lot of fun to write tests for code that takes in complex data types and manipulates them. I started writing tests for smart blocks but just building the smartblock data was time consuming. Perhaps there are better ways as I’m not a testing expert. You can look at the tests to see what frameworks are used. Any help in this regard is appreciated.
That Debugger looks good. I’ll take a look at it. I was also thinking
about a guide from a background of no PHP development (i.e. me), looking
at things like
Installing required packages
Required setup - Postgres, etc
Suggested git workflow (maybe linking to git basics, etc)
Testing - developing and running tests
Debugging - xdebug
In terms of testing, we have very little guidelines and have been very
lack in terms of coverage because the coverage for the existing code
base was so sparse. It’s not a lot of fun to write tests for code that
takes in complex data types and manipulates them. I started writing
tests for smart blocks but just building the smartblock data was time
consuming. Perhaps there are better ways as I’m not a testing expert.
You can look at the tests to see what frameworks are used. Any help in
this regard is appreciated.
There are several frameworks in use it appears:
Selenium - automated testing of
web-browsers. It is Java based and the script that uses it
(tests/run_selenium.sh) downloads it, if needed.
Python tests are run on the various python applications involved
PHPUnit - PHP unit testing. This is used to
test the majority of the code. It also requires some setup that
airtime_mvc/tests/run_tests.sh handles - mainly around rabbitmq setup.
Yeah, writing tests is never the fun part of programming. Unfortunately
my PHP knowledge is next to zero, otherwise I would try work on them. I
do intend to improve my knowledge so that I can start working on the
code-base, but it will be a while before I get a chance.
I’ve found following the Travis CI stuff has been helpful in
understanding the testing process that happens currently. I will try
formalise that over the coming week into usable documentation.
PHP itself isn’t too complicated to learn, it has a syntax similar to C but is dynamically typed and has a lot of swiss-army type of functions. What makes LibreTime more complex from a developer perspective is that we are using an older version of the Zend PHP MVC along with a lot of odd javascript libraries and a lot of custom written hacky jQuery javascript. So even modifying a simple part of the interface usually involves altering around 3-4 different files. Are there any programming languages you are more familiar with or have done some development in ?
This is likely the result of the code being built up at SourceFabric by a number of different developers who were learning the various frameworks while they put together the functionality. It really could use an update/overhaul and rewriting in a newer javascript framework so that development could be simplified in my opinion. But knowing how pursuing grand visions without adequate time budgeting can result in vaporware I’ve put most of my time towards building on the existing framework so that it can be at least somewhat stable and bug-free enough to be usable for most stations while we investigate alternative paths.
In regards to testing, I haven’t been able to get the Selenium tests working. The PHPUnit stuff works but is a pain to develop the data to feed into the functions to properly test them, which is why I’m assuming there is so little coverage. If you wanted to spend some time learning PHP, working on the testing might be a good place to start. I haven’t finished my PR to add testing to the smart block code because I lost interest with the limited time I have to work on things. It is working but should test more scenarios and I think at this point it just tests whether the getListofFilesUnderLimit criteria loads any tracks (not the correct ones) https://github.com/LibreTime/libretime/pull/269 - If you want to play around with that it might be useful and I’d be happy if you wanted to finish it.
One last thing regarding xdebug, I was working with PHPStorm as my IDE (although Eclipse or another free IDE should work) but due to the way most of the PHP code is called by AJAX vs. being loaded directly the only way I found I was able to actually hook into the codebase was to setup my IDE to listen and then manually add the xdebug_break() function where I wanted to analyze.
I work a lot in C/C++, Python and Java. I am somewhat familiar with JavaScript as well (working with GNOME Shell extensions, so I understand the language, but not the frameworks).
Yeah, working with old frameworks is difficult, but overhaulling such a big code base is even more so.
Sure. I’ll get a start on that in a week or so when I get back to work. Seeing as I am not running LibreTime in production yet (We have an airtime instance waiting for the first stable Debian release with it packaged), writing tests sounds like a good way to get involved. I’ll also try flesh out the docs around testing/development while I go
Hmm, ok. I use vim as my IDE, so I shall do some digging into plugins that help with xdebug and if push comes to shove print statements work
Will we run into any issues with debian packages including the various php & python libraries currently included by composer and pip. I know that they are sensitive to specific versions etc at times.
Yeah. That EOL is definitely a good motivator. We probably should look at moving from python 2 to python 3 for the same reason (2020 EOL)
As long as we’re consistent within a stable release we’re fine - there are no major version upgrades to a release after the freeze and official release. We can also specify exact versions required for dependencies. Though we should try ensure we’re developing against the latest releases of libraries to avoid the headaches. (Which I know is easier said than done!)
