How to start using Agile Toolkit 4.2
Preparing the environment
Agile Toolkit 4.2 requires PHP5.3+. You might need to upgrade. Other than that, the regular installation guide applies.
You may use Windows, Linux or MacOSX but you will need to make sure "git" is installed. I will be providing you with the shell "git" commands but you are welcome to use any GUI.
Official client for GitHub is a great software, but it has very weak support for submodules. As a result you might need to delete "atk4" and "atk4-addons" folders and then clone them as individual projects. You can't clone same repository several times, therefore you'll need to use symlinks if you are running multiple instances of "atk4"
There are daily updates to 4.2 and you should be always running most recent version if you are reporting any issues or trying to fix anything. Git is much easier to update then messing with ZIP files. If you do want to use ZIP, then GitHub will provide you with the "Download" button.
One of the core Agile principles is a test-driven development. Agile Toolkit now have a separate project, which implements many unit-tests.
The UI of Agile Toolkit is not being automatically tested but if you want to test your UI, you should use Selenium.
Testing interface is available for you in your own projects. Be sure to use testing to a full extent.
Setting up testing environment
Before actually using Agile Toolkit, we need to make sure that it works in a test environment.
Create directory Sites/atk42 where all the code will reside. I will assume that it can be reached on http://localhost/atk42. Go into that directory and check out the 4.2 branch of Agile Toolkit (it's 8 megabyte repository, be patient)
$ git clone git://github.com/atk4/atk4.git
$ cd atk4
$ git checkout 4.2
$ cd ..
atk4-addons are no longer mandatory to use Agile Toolkit, but I will return to them in the addon developer guide. Next, you will need to "fork" the test-suite. This is to make sure that you can easily commit back your own test-cases. Open this link, then click "fork". It will create repository under your account. I'll assume that your account is "joe" and that you are now on https://github.com/joe/atk4-testsuite/. Proceed to check out your own version of test-suite.
$ git https://firstname.lastname@example.org/atk4/atk4-testsuite.git
If you have "atk4" and "atk4-addons" inside atk4-testsuite, delete them. If your database needs changing, create atk42/atk4-testsuite/config.php and copy relevant lines from config-default.php adjusting them with the right values.
You are now ready to open http://localhost/atk42/atk4-testsuite/ and you should see list of tests. Click on test called "db" and make sure that your database conneciton works OK. You do not need to cerate any tables. Test-suite creates temporary tables for you.
Open file atk42/atk4-testsuite/page/db.php in your editor. Try to add tests or change them. You will notice that at the start of the file the property $proper_responses is initialized. Once your tests are outputing right value, you can copy value of this variable from the text-area on the test-page into your source file. That's all, no more "assert()" and "verify()".
Be aware that there are a class called "Page_Tester" (see page/dbparam.php on how to use it) which provides a general-purpose testing and then there is DB-test which extends tester into some SQL-related testing (see page/db2.php for a good example).
Of course you can also add a regular pages with regular code snippets which you will find on your on-line documentation
Things to test
As you go through documentation, please try examples. They should work properly. If not, please report an issue. If you are unsure how to use any feature, please ask in the list.
Once you have tried some basic things with the test-suite, you can then try to use atk4 in your application. This will probably require you to do a lot of changes. Our goal is to introduce as much compatibility between 4.1.4 and 4.2 as possible, but things will need to be changed anyway. Please share what changes you needed to perform.