How to set up a Colouring platform development environment - colouring-cities/ccrp-technical-manual GitHub Wiki

Mikle and Mateusz Please could you edit or move to the 'history' page and to the 'how it works' page where applicable- thankls then will be group editing

Below are additional diagrams produce by Ed Chalstrey in 2022 showing the development flow for open code development and platform testing at the Phase 1 (2016-2022) to Phase 2 (2023 onwards):

Ed current development flow

ed long term development flow Image produced by Ed Chalstrey 2022

Overview of Colouring Cities platform set-up Key steps

Commitment by CCRP participating academic institution to CCRP aims and protocols; CCRP partner legal team assessment to check wording and identify inclusion of additional legal disclaimers etc. as required; securing of set-up grant;
Inclusion of CCRP partner on the Alan Turing CCRP website page, and on open manual pages-including a dedicated country page;
Provision of access to free Colouring Cities domain name from the Alan Turing Institute;
Provision of acccess to co-work on Colouring Cities core colouring GitHub repository and documentation and set up environment;
One-one-sessions available from the Alan Turing Institute, as well as access to group CCRP technical meetings
Coordinate server access and credits;
Secure access to open building footprint data;
Work with PI Tailor to tailor subcategories to suit geographic location- translation and content PI to suit edit to edit text & CCRP partner institution
Maintain, manage and develop platforms
Work on core colouring code with CCRP partners and release country specific code
Co-work on papers and support research initiatives

Information for engineers transitioning from Colouring London to the new Colouring Cities colouring-core Configuration

Our aim is to maximise collaboration amongst the codebases represented in https://github.com/colouring-cities, as well as maximising sharing of standardised datasets. The CCRP strategy for 2023 involves a transition from CCRP partners forking and adapting Colouring London prototype to suit national/regional requirements, to a model allowing CCRP PI and engineering teams to co-work on Colouring Cities core code to increase efficiency, lower engineering costs for countries, and maximise skills and knowledge sharing

Updated below by Mike Simpson, CCRP Research Software Engineer for the Alan Turing Institute/Newcastle University (Feb 2023)

As we move from the Colouring London prototype to the expanding Colouring Cities Research Programme (CCRP), we have decided to make several changes to the colouring-cities organisation on GitHub to enable better collaboration between the various projects.

We do not expect these changes to significantly impact the existing “Colouring...” projects. However, we have detailed the changes in this document to minimise confusion and explain our vision for the CCRP moving forward. Colouring Core, The idea behind creating the ‘colouring core’ platform is to have a single base repository from which all other Colouring Cities projects are forked. That way, developers on all projects can share their features and innovations with the rest of the CCRP by folding those changes back into the Core platform.

Colouring London transition

The problem was that several projects were already forked from the Colouring London repository. For example, the two projects shown in the diagram below. Screenshot 2023-02-15 at 13 50 16

Introducing a new ‘core’ repository into this organisation structure would have led to additional work for the Colouring London team, and all the projects forked from Colouring London. Instead, we decided to go with a new structure, which involved renaming some of the Colouring Cities Repositories: • We renamed the ‘colouring-london’ repository to ‘colouring-core’. • A new ‘colouring-london’ repository has been created, forked from ‘colouring-core’. We appreciate that this may cause some confusion, but we decided it was the best way to move the project forward.

The new organisation structure looks like this: Screenshot 2023-02-15 at 13 51 02

This change puts the onus on us to make changes to the Core and London platforms, rather than on our partners to have to adapt to fit in with this new structure.

Moving Forward The new structure is intended to make easier to customize local platforms while minimising the divergence in codebases between project and allowing certain new features to be merged back into the core platform. Ideally, all CCRP projects should be forked from the new Core repository and should contribute any useful features back to the Core Platform.

We encourage all Colouring Cities projects to implement new city-specific things by modifying the colouring-core repository via pull requests and configuring it locally, rather than making changes locally and diverging from the core repository, where possible. The aim of the restructure is to minimise the amount of duplicate effort and city-speicifc code in each project, and to ensure that new developments and features can be shared with all CCRP members.

Please report and/or submit Pull Resuests about any London-specific things that you find in the code, so that they can be moved into the new configuration file system (see other document attached to this email for details).

Possible Problems We do not expect these changes to cause any technical problems, beyond some minor confusion. Projects previously forked from Colouring London automatically update on GitHub, and their relationship with the core repository will be preserved. There may be some issues, however. For example, you may have cloned the old ‘colouring-london’ repository using GitHub Desktop. In that case, the application may now point to the new ‘colouring-london’ repository instead of automatically updating to point to ‘colouring-core’.

Please ensure that any links and references in your code, documentation and applications are updated to reflect this new structure. Also, please double-check that you are using the correct repository before checking in any code.

Feedback If you experience any issues with the new organisation structure, feel free to give us feedback using the discussion features on GitHub or create an issue.

Colouring Cities core updates

As part of the transition from the Colouring London prototype to the expanding Colouring Cities Research Programme (CCRP), we have decided to implement some changes to make it easier for other projects to create and customise their own Colouring Cities platform. The first stage of this process has been the addition of a new config file, used to specify certain elements of the Colouring Cities interface. These changes have now been deployed on the new 'colouring-core' and 'colouring-london' repositories.

Using CC-Config

To customise the site, you will need to edit the file “app/src/cc-config.json” and modify the text strings (red in the example below) and the values (shown in green below) to customise the Colouring Cities interface.

For example, changing the "cityName" from "London" to "[Your City Name]" will replace the logo and other properties across the entire site to use your city name instead of London. You are also encouraged to update your githubURL to refer to your specific version of the project on GitHub. Also, please update the privacyStatement to inform users how their data will be stored (and what safeguards are in place).

  Using/Modifying CC-Config in your Colouring Cities Code For Developers, Software Engineers and advanced users, here is a more detailed overview of how the CC-Config features work. The CCConfig code is defined in app/src/cc-config.ts and contains all of the variables that can be used in your code.

The value of these variables are defined in JSON format in app/src/cc-config.json

And to use the cc-config parameters in your code, you will need to import the files using the following lines of code import { CCConfig } from '../../cc-config'; let config: CCConfig = require('../../cc-config.json')

Colouring Cities Configuration.docx

Colouring Cities Core Platform.docx