Camdram is an open source project developed by a team of volunteers for the benefit of the Cambridge student theatre community. We use this repository to host the code that runs Camdram and to co-ordinate our work, however we welcome anyone to contribute bugs and suggest new features.
The steps required to set up a development checkout of Camdram are detailed below. For the sake of brevity, these instructions assume that the reader is familiar with a number of technologies, such as developing on a Linux based platform, using Git and GitHub.
New releases are made on the
master branch every so often using the GitHub interface. This automatically generates a changelog and pushes the new release into production at https://www.camdram.net/. The latest changes can be seen at https://development.camdram.net/ which always reflects the
HEAD state of this repository.
If you encounter any problems with the instructions below, please create a GitHub issue or send an e-mail to email@example.com. We also have a live chat hosted on Gitter which you can use to quickly and informally get in touch with the development team.
1) Install programs
You will need to install the necessary package dependencies required to run Camdram. PHP version 7.3 or greater is required.
Debian/Ubuntu and Derivatives
The command below can be run on recent Debian-based distros (including Ubuntu and the Windows Subsystem for Linux).
sudo apt-get install git-core php php-cli composer php-curl php-intl php-sqlite3 php-gd php-json php-mbstring php-xml php-zip
You will need to have Homebrew installed. The following command appears (from minimal testing) to install everything required on recent versions of macOS.
brew install git php composer
Installation methods on other distros and operating systems will vary.
2) Create a local version of Camdram
The steps below assume that the Composer PHP package manager is installed globally on your system. If it is not available in your distro's repositories, alternate installation methods can be found at https://getcomposer.org/download/.
Note: some of the SQL database operations performed by the
composer commands below are memory-intensive. Default installations of PHP tend to set the memory limit of a PHP script to a value which will undoubtedly cause fatal errors. To prevent this, find your
php.ini file (location varies by system) and change the
memory_limit setting, to something like
memory_limit = 1G (a gigabyte is definitely sufficient - you may be able to get away with a lot less if you prefer). Alternatively you can call the PHP interpreter like so:
php -d memory_limit=1G $(which composer) etc.......
The command below will download and set up a Camdram checkout in a new folder called
composer create-project camdram/camdram camdram dev-master --no-interaction --keep-vcs
After obtaining a copy of the code, change into the newly created directory and start a local web server:
cd camdram php app/console server:run
You should then be able to visit http://127.0.0.1:8000/ in your web browser to see your personal version of Camdram's homepage.
3) Run test suite
Camdram has a limited but growing automated test suite, which can be used to ensure your checkout is working and check for certain regressions after making changes. It can be executed by running:
4) Create a fork
Camdram's development model follows the standard idioms used by FOSS projects hosted on GitHub. If you are just interested in experimenting with the codebase, no further steps are necessary, but if you'd like to contribute then you will need to create a fork.
After creating a personal fork, you can repoint your checkout using the commands below.
git remote rename origin upstream git remote add origin firstname.lastname@example.org:your-github-username/camdram.git
We run Camdram as a meritocracy: anyone who has a reasonable number of pull requests accepted will be given access rights to commit straight to the Camdram repository
5) Write some code
It is a good idea to create a "feature branch" before starting development, so that the pull request will be named appropriately:
git checkout -b my-cool-feature
Some useful tips:
- The site uses the Symfony PHP framework - read the documentation.
- Use the GitHub issue tracker to discover and discuss issues to work on. If you think you know how to do something, write the code, commit it, and submit a pull request.
- If you want to discuss how to implement a new feature or how to fix a bug, get in touch with one of the developers. It would probably be wise to get in touch before starting on any significant projects to avoid wasted effort!
- Visit http://try.github.io/ if you're not familiar with Git.
- Code should ideally conform to the style guide here: http://www.php-fig.org/psr/psr-2/. If this is far too daunting, a poorly styled but functional improvement is better than no improvement. You can use http://cs.sensiolabs.org/ to (mostly) clean your code up after writing it.
Depending on the type of change, ensure it works as a logged-in and/or non-logged in visitor. You can grant administration rights to your user account (which allows you to create and modify any Camdram content) by running
php app/console camdram:admins --email@example.com
6) Submit your changes
git add file1.php file2.phpfor each file you wish to include in the commit
git commitand enter a message describing the changes you have made
git pushto send your changes to GitHub
It is good practice to include the relevant issue number (prefixed with a hash #) at the end of the commit message - this will cause your commit to be linked to the issue page on GitHub.
Once your changes are pushed to your Camdram fork on GitHub, you can submit a pull request to have it included in Camdram.
Please note: we automatically display the names of some contributors on our development page as a way of saying thanks! By submitting your changes you are acknowledging that you are happy for this to happen.
7) Pull in other people's changes
At a later date, once your local repository has become out of sync with Github (because other people have make changes), you can run the following commands to pull in other people's changes and update your checkout:
git fetch upstream git merge upstream/master
The following commands may need to be run after the above, if the dependencies, database schema or JS/CSS assets have changed.
composer install php app/console camdram:database:refresh php app/console camdram:assets:download
8) Read the Wiki
The Wiki has various pieces of information about both the current and in-development versions of Camdram. Reading through those pages can give insight into the more esoteric parts of the system. You can suggest ideas for new articles using the contact details above.
The following wiki pages detail how to create a server set-up that's more similar to the version of Camdram at https://www.camdram.net/:
- Setting up for JS/CSS development
- Setting up a MySQL database
- Elasticsearch setup guide
- External API registration
- Setting up an Apache virtual host
Camdram is released under version two of the GNU General Public License.
Copyright (C) 2014–2019 The Association of Cambridge Theatre Societies and contributing groups.