TMS:Website Development Log

This is a development log for the main Mars Society website.

The most recent version of the website (v6) was designed by James Burk and Shawna Armstrong.

Local Workstation Setup

• OS: I use Windows Subsystem for Linux on Windows 10. Set this up by downloading Ubuntu 18.04 from the Windows Store. One could also use MacOS or a native Linux installation for development, but the toolset would be slightly different in some cases.
• Locally installed tools:
  • Windows:
    • Editor: Visual Studio Code
    • S/FTP client: Filezilla
    • DB browser: HeidiSQL
    • Source control & Deployments: Git for Windows
  • Ubuntu (within WSL)
    • Server: Apache
    • Database: MariaDB (this can also be installed on the Windows side. MariaDB Is a drop-in open-source replacement for MySQL, which is now owned by Oracle)
    • Package manager: Yarn or NPM (I prefer Yarn due to speed, but you can use either; just not both! if you switch, delete the lock files -- yarn.lock and/or package-lock.json )
    • JS Runtime: Node
    • CSS Compilation: Gulp
    • Testing tool: Browsersync
    • Source Control & Deployments: Git
    • Wordpress maintenance tool: WP-CLI

I create a C:\Sites folder with Windows Explorer and associate that within Ubuntu by using "ln -s" to make it ~/Sites.

I set up the local Apache to host a domain such as "marssociety.test" to point to localhost with that ~/Sites directory. This allows me to easily use a browser in Windows 10 to test the local instance of the site, running on Apache.

Set up Wordpress locally

• Reference: https://hellojason.net/blog/how-to-setup-wordpress-locally-on-windows-subsystem-for-linux/
• Install wp-cli to live at /usr/local/bin/wp
• Install and configure Apache to use local Sites folder as above, creating a new .conf file and enabling it.
• Edit Windows hosts file to use .test domain
• Run the WP-CLI command "wp core download" in ~/Sites/v6
• Update the wp-config.php use local database and hostname as "127.0.0.1" (loopback IP address).
• Test the configuration by opening a browser and doing Wordpress Setup.
• Ready to go!

Setup Theme Development

• Download understrap theme from Github (I prefer cloning) into /wp-config/themes. Understrap is a great starter Wordpress theme because it gives you the excellent Bootstrap UX library and Font Awesome icon library.
• Download our custom tms2019 theme from Github (it's derived from understrap-child and we try to keep it in sync).
• Run "yarn install" from the understrap directory.
  • Note #1: This may result in warnings about jquery and popper.js, if so:
  • Install jquery@3.3.1 and popper.js@1.14.7 using "yarn add"
  • Note #2: Understap is currently using gulp 3.9.1 which is slightly older than the current release (gulp v4). this is to avoid some compatibility issues.
• Switch to the tms2019 directory and run "yarn install".
• Update browserSyncOptions in gulpconfig.json to reflect your local machine.
• Use "gulp watch-bs" to begin development.

Benefits of this workflow:

All custom CSS styles are located in sass/_tms2019.sass and _tms2019_variables.sass. Do not edit the *.css files directly, since Gulp will compile those for you from the SASS files.

Using "gulp watch-bs" (with Browsersync) or "gulp watch" (without Browsersync) will auto-compile any changes to the SASS files into the final CSS.

Gulp and Browsersync will automatically compile and update the browser as you do development, greatly speeding up the overall workflow and eliminating manual deployments & refreshes (I found these took the majority of overall time with my previous development workflow)

Deployment Methodology

I plan to develop the site locally using the above setup, and to test it extensively.

Then I plan to push all changes to github, and use github to deploy to the webhost.

Reference: Efficient Wordpress Development Workflow by Jason Yingling