LaLa Theme 4 Development Summary

001 Development Summary.md

LaLa Theme 4 Development

• The LLT4 development systems are in place to achieve a number of goals in order to:
  • Expedite the creation, update, and management of both parent and child theme sets,
  • Facilitate and utilize powerful development tools and structured systems,
  • Minimize frontend asset size and volume, and
  • Simplify the process of deploying changes to live sites

I. Setup and Environments

A. The Dev Server

• Development should occur on a specified "dev" environment and never on the production server itself
• A dev environment could be a remotely-hosted server, a local setup, or anywhere the developer feels confortable
• LLT4 uses the following technologies/utilities; the following should be available on the development environment:
  • Git (Version Control)
  • NPM (Package Management)
  • WebPack (Asset Bundling)
  • PHP 7.X (Web Processor)
  • MySQL 5.7+ (Database Technology)
• Depending on your OS and machine the installation process could vary; be sure to follow the instructions based on your specific requirements
• Any web server technology compatible with WordPress can be used (Apache, NGINX preferred)
• Once the above technologies are set up, a clone of the master repository should be made
  • Clone the repo: git clone git@github.com:lalaprojects/{repo_name].git
  • Install the required modules npm install

B. Version Control

• LLT4 uses Git version control with GitHub as a source for push/pulling
• Before pulling down the latest repository for development, the developer needs to set up SSH keys for in order to access the repository

C. Asset Bundles

• LLT4 uses two sets of asset bundles to isolate dev and production environments
  • Production-level bundles are located in .../public/css and .../public/cs
  • Similarly, dev-level bundles are located in .../public/dev/css and .../public/dev/js
• Two sets of bundles are used to that production-level assets can only be explicitly overwritten with npm run prod
• When first setting up (and for every repo pull thereafter), npm run dev should be run in both the parent and child theme so that dev-level assets are available
  • npm run dev and npm run watch will produce the same asset files
  • npm run watch will listen for any changes in the theme and automatically run npm run dev

II. Development Timeline & Notes

Development occurs in blocks of tasks as defined by both the project manager on a macro scale and you as the developer on a local scale. An example of a full cycle of development is summarized below:

1. Development begins
2. Navigate to the proper directory on a dev environment
3. Make sure your repository is updated: git pull origin master
4. Start up the webpack bundler to start building the dev bundle: npm run watch
5. Complete required tasks through development
6. Test new features and ensure changes are production-ready
7. Fire up the prodution bundle: npm run prod
8. Update the version number in style.css
9. Add your changes to a new commit: git add .
10. Create a new commit with a meaningful message: git commit -m "Made changes to ..."
11. Generate a new tag that matches the new version number in style.css: git tag v1.0.1 -m "What is new in this version..."
12. Push your changes up to the master repository: git push origin master
13. Make sure you are in the master branch and push your new tags: git push origin --tags
14. Navigate to the wp-admin backend fo the relevant site(s)
15. Go to Appearance -> Themes and run the automatic updater

A. Tickets

• The impetus for development could be a number of things including but not limited to:
  • A new feature is requested
  • Refactoring is required on existing code
  • Errors or bugs need to be resolved
• Requests usually come in as a ticket covering the need for changes to a specific code base
• Each development session (and subsequent commits to the master repository) should only cover the scope of the work requested
  • This is both keep development intentions and purposes organized and ease in historical analyses and potential rollback capabilities

B. Using WebPack

• The WebPack asset bundler takes all of the relevant files for each theme, processes them, and smushes and minimizes them into a single asset
• This allows to call in a single app.css and app.js file on the frontend with any and all changes
• Themes are set up to use the Stylus CSS framework

C. Using NPM Scripts

• The NPM scripts defined in package.json are used to speed up the boring parts of development such as bundling and compilation
• By running npm run watch, WebPack will be initialized and keep watch for any changes you make to asset files, rebundling each time it sees one
  • This creates a development-level bundle that will aid in troubleshooting and testing
• When changes are ready for production, running npm run prod will run a routine that will produce a production-level bundle
  • This is similar to the development bundle but removes debug information and minimizes content more effectively

D. Updating with GitHub

• Themes and production sites are equipped to use automatic update checkers to match changes with the master repository
• The themes will compare the version value in style.css with the latest tag in GitHub
• If the installed version is behind the GitHub version, an update can be made
• When pushing changes to GitHub, it is important to create a new tag when new changes are ready for production

III. Theme Organization and Structure

• LLT4 uses the standard WordPress parent -> child theme inheritance feature
• Each new child theme is forked from the template theme, which is updated with the latest and greatest child theme initializing features
• All of the required hooks (for both parent and child themes) are implemented in the parent theme to keep the child themes as light and flexible as possible
  • E.g., asset enqueueing for child themes occur in the parent theme by checking if a child theme is being used

A. Resource Structures

• In LLT4, resources are considered any partial piece of display, style, or layout asset that is used to render the site
• Here, template partials, styles, and scripts all fall under the "resources" umbrella
• A vast majority of changes and alterations made to themes will be made to resources

B. Partial Templating and Inheritance

1. Partial Views

• LLT4 uses template partials to build a full, rendered view
• Partial views are all contained in the /resources/views folder
• The parent and child theme each have their own set of asset bundles
  • "Assets" are files that have to be enqueued, such as stylesheets and scripts
• Partials can be overwritten in the child by mimicking the partial path
  • E.g., the {child_dir}/.../header/banner.php will be used instead of the {parent_dir}/.../header/banner.php if the file exists
• The ll4_view() function can be used to call in partial views with the inheritance logic already baked in

2. Stylesheets

• While the styles contained in /resources/(sass|stylus|css) share a similar structure to views, it is only for organizational purposes
  • Child theme styles files will not overwrite parent files (since they use different asset bundles)
• In addition, the /resources/img files are the source for any theme images, but are used mostly for background images and other CSS-releated needs

3. Scripts

• Scripts are split up by functionality with each folder representing an enclosed function
  • E.g., "Smooth Scroll" and "Google Map" functions are all contained in their own directories
• Different scripts are explicitly called in by the /resources/js/app.js file