Joomla! Programmers Documentation

Getting Started¶

If you would like to contribute to Joomla! core code you will need a GitHub account. It is free and takes moments to set up. You will also need a working [LMWX]AMP stack on your local laptop or workstation. You will almost certainly need an IDE too!

Fork joomla/joomla-cms on GitHub¶

Log in to your GitHub account and type joomla/joomla-cms in the Search or Jump to... box at the top left. You need to be in the original joomla-cms repo.

Click the Fork button at the top right of the screen. This will bring up a form asking you to confirm details of the fork you want to make. It is usually sufficient to select the green Create fork button.

That will make a complete copy of the joomla-cms repo as it exists at this time in your own account. If someone updates the original later you can use the Sync fork button to bring your repo up to date.

Clone your Github fork locally¶

The local Apache web server uses a specific folder for individual web sites. For example, on a Mac it may be /Users/username/Sites. You may have many sites for testing and developing different projects, each in a separate subfolder. The clone process will create a folder within your current folder so first open a terminal window and switch to your sites folder:

cd ~/Sites

Then type in the clone command:

git clone https://github.com/yourusername/joomla-cms.git

This may take a long time! Switch to the joomla-cms folder and list what is in it:

cd joomla-cms
ls -al
total 2192
drwxr-xr-x   44 ceford  staff    1408 26 Aug 17:28 .
drwxr-xr-x  107 ceford  staff    3424 26 Aug 17:26 ..
-rw-r--r--    1 ceford  staff    2174 26 Aug 17:28 .appveyor.yml
-rw-r--r--    1 ceford  staff   13689 26 Aug 17:28 .drone.yml
-rw-r--r--    1 ceford  staff     388 26 Aug 17:28 .editorconfig
drwxr-xr-x   12 ceford  staff     384 26 Aug 17:28 .git
drwxr-xr-x   11 ceford  staff     352 26 Aug 17:28 .github
-rw-r--r--    1 ceford  staff    1765 26 Aug 17:28 .gitignore
-rw-r--r--    1 ceford  staff    4076 26 Aug 17:28 .php-cs-fixer.dist.php
-rw-r--r--    1 ceford  staff    6748 26 Aug 17:28 CODE_OF_CONDUCT.md
-rw-r--r--    1 ceford  staff   18092 26 Aug 17:28 LICENSE.txt
-rw-r--r--    1 ceford  staff    4469 26 Aug 17:28 README.md
-rw-r--r--    1 ceford  staff    4942 26 Aug 17:28 README.txt
drwxr-xr-x   12 ceford  staff     384 26 Aug 17:28 administrator
drwxr-xr-x    6 ceford  staff     192 26 Aug 17:28 api
drwxr-xr-x   20 ceford  staff     640 26 Aug 17:28 build
-rw-r--r--    1 ceford  staff    6422 26 Aug 17:28 build.xml
drwxr-xr-x    3 ceford  staff      96 26 Aug 17:28 cache
drwxr-xr-x    4 ceford  staff     128 26 Aug 17:28 cli
-rw-r--r--    1 ceford  staff     461 26 Aug 17:28 codeception.yml
drwxr-xr-x   19 ceford  staff     608 26 Aug 17:28 components
-rw-r--r--    1 ceford  staff    3867 26 Aug 17:28 composer.json
-rw-r--r--    1 ceford  staff  419222 26 Aug 17:28 composer.lock
-rw-r--r--    1 ceford  staff    6858 26 Aug 17:28 htaccess.txt
drwxr-xr-x    8 ceford  staff     256 26 Aug 17:28 images
drwxr-xr-x    6 ceford  staff     192 26 Aug 17:28 includes
-rw-r--r--    1 ceford  staff    1068 26 Aug 17:28 index.php
drwxr-xr-x   16 ceford  staff     512 26 Aug 17:28 installation
drwxr-xr-x    5 ceford  staff     160 26 Aug 17:28 language
drwxr-xr-x    7 ceford  staff     224 26 Aug 17:28 layouts
drwxr-xr-x   16 ceford  staff     512 26 Aug 17:28 libraries
drwxr-xr-x   27 ceford  staff     864 26 Aug 17:28 modules
-rw-r--r--    1 ceford  staff  538644 26 Aug 17:28 package-lock.json
-rw-r--r--    1 ceford  staff    3983 26 Aug 17:28 package.json
-rw-r--r--    1 ceford  staff     639 26 Aug 17:28 phpunit-pgsql.xml.dist
-rw-r--r--    1 ceford  staff     642 26 Aug 17:28 phpunit.xml.dist
drwxr-xr-x   26 ceford  staff     832 26 Aug 17:28 plugins
-rw-r--r--    1 ceford  staff     422 26 Aug 17:28 renovate.json
-rw-r--r--    1 ceford  staff     764 26 Aug 17:28 robots.txt.dist
-rw-r--r--    1 ceford  staff   26187 26 Aug 17:28 ruleset.xml
drwxr-xr-x    5 ceford  staff     160 26 Aug 17:28 templates
drwxr-xr-x    8 ceford  staff     256 26 Aug 17:28 tests
drwxr-xr-x    3 ceford  staff      96 26 Aug 17:28 tmp
-rw-r--r--    1 ceford  staff    2974 26 Aug 17:28 web.config.txt

Build a working Joomla site¶

The downloaded development branch needs some extra steps to create a working Joomla site. This from the README.md file:

composer install
npm ci

Again, it will take a while and you will see flash past the commands to compile the javascript and css files. When done you can point your browser at localhost/joomla-cms and go through the normal install process.

The site should now work as any normal Joomla site.

Making changes¶

If you would like to contribute to the Joomla CMS you need to progress through the following stages:

• Create and Checkout a branch in your local repo. This is very important! It will contain a record of the changes you propose to make to the original.
• Make and Test Changes and don't forget to check that your code conforms to the Joomla coding standards.
• Commit and Push your changes to your remote GitHub repo.
• Make a Pull request in your remote repo to ask for your branch to be merged into the main branch.

Create and Checkout a branch¶

In the terminal window, make sure you are in the root of your site, then:

• git branch mypatch1
• git checkout mypatch1

where mypatch1 should be some short distinctive piece of text that allows you and others to distinguish between various branches. For example, it could start with your initials and finish with a succinct description of its main purpose, for example cffixabc.

Make Coding Changes¶

This can be as trivial as correcting a language string or as complex as a major new feature. Or you might like to tackle a problem reported in the Issue Tracker. You can always ask for advice or comment there before plunging in to coding.

Local Testing¶

It is essential that you test your proposed changes locally before making a pull request. You will have been checking your local joomla site to see that your code appears to work properly. However, if your code involves changes to javascript or css files you will need to recompile your sources. So go back to your terminal window and enter:

npm ci

If you site works without error you are ready to make a pull request.

Commit and Push¶

Easy with an IDE. In VSCode:

• select the + button in the Changes list to commit the changes to the local repository.
• Select the Source Control ... button followed by Pull, Push / Push To... / and then select your own remote repo to push the changes from your local repo to your remote repo.

Make a pull request¶

Login to your account on GitHub and select your own joomla-cms repo. In the Code section select the branch you wish to commit from the Switch branches drop-down list (marked with the branch icon). Click the Contribute button and then the Open Pull Request button.

After making a pull request some automatic checks are carried out. All being well after a few minutes you will see this result:

ToDo

Remote Testing¶

Your pull request will go into a testing phase where the Joomla developers can examine your code and test it to see if it works and whether it stops anything else from working. Even if it works, others may regard the proposed change or method of implementation as inappropriate and decline to merge your pull request into the main code. Do not take umbrage! It happens all the time, even to the experts. Just move on to something else.

Github workflow¶

In git you may have multiple remote repositories. You defined one remote repository when you cloned your own remote repo. You may also add the original repo to your list of remote repos. Example:

git remote -v show
Manual	https://github.com/ceford/Manual (fetch)
Manual	https://github.com/ceford/Manual (push)
origin	https://github.com/joomla/Manual.git (fetch)
origin	https://github.com/joomla/Manual.git (push)

This allows you keep your own fork and clone up to date from your local computer. You just need to pull and merge the original source into your local clone and then push your local clone to your remote fork. The following diagram illustrates the process: