This section has some general guidance on how you can get started developing applications for us. We assume a working knowledge of git and Unix-like operating systems.
?> UIS members may gain such a knowledge through our LinkedIn Learning organisational account.
The majority of our products are developed on GitHub. When you join the DevOps team you will be asked for your GitHub account name. You may wish to use a personal account or create one named after your crsid.
The git version control system works best when used in combination with SSH. You will want to associate a SSH key with your account.
?> For more information, see the GitHub documentation on SSH.
GitHub has a notification system which can be used to notify you over email when things of interest happen. Having notifications enabled is useful to keep you in the loop as any changes you make are reviewed, commented on and, eventually, merged. You can configure notifications in the GitHub settings.
The usual naming convention for repositories is {product}-{component}. For
example, the web application for the Media Platform is at
uisautomation/media-webapp.
?> Having your repository cloned to a matching {product}/{component}
directory is considered best
practice.
If you install hub, you can clone a local repository and create your own fork:
$ cd ~/repos # or, wherever you keep your clones repositories
$ mkdir media && cd media
$ hub clone uisautomation/media-webapp webapp && cd webapp
$ hub fork # creates a fork and adds a new remoteMost of our products use CircleCI for continuous integration and development. You can set up CircleCI integration for your fork by visiting https://circleci.com/gh/{username}/{repository} in your browser and clicking the "Follow Project" button.
For example, to configure bb9e's fork of iar-backend, visit https://circleci.com/gh/bb9e/iar-backend.
The README file in a repository will contain any special information about getting started with a project. For example, you may need to obtain and configure some product-specific credentials. This file may also contain any CircleCI specific configuration you require for your fork.
?> From the repository root directory, you can open the corresponding GitHub
repository web page and read the README file using the command
hub browse.
This section is specific to getting started developing our webapps.
For webapps, we have settled on a solution for local development based on docker-compose. This allows for a consistent development environment even if an individual Developer's machine varies.
Many of our products use Codecov for code coverage checking. You can set up Codecov integration for your fork by visiting https://codecov.io/gh/{username}/{repository} in your browser.
For example, to configure bb9e's fork of iar-backend, visit https://codecov.io/gh/bb9e/iar-backend.
Make sure that the latest version of docker and docker-compose are installed on your machine. Using docker-compose allows us to run tests and develop within an environment very close to that we deploy in.
Tests for the webapp can be run inside a container using the ./tox.sh script
present in many of our webapps. Generally this will check that the documentation
builds, run code style checks and run the test suite. A code coverage summary
will be shown after the tests run.
A development server can be started with ./compose.sh development up. The
web application is then usually available at http://localhost:8000/.
For applications making use of React to render the frontend, we usually have automatically generated styleguidist documentation for React components at http://localhost:6060/.
For applications which send email, we usually have a MailHog instance running at http://localhost:8025.
!> This section is likely to change significantly.
We deploy applications using configuration in a {product}-deploy repository
on GitHub. Usually these repositories are private. See the README in any one
repository for an overview of how deployment happens for that product.