CONTRIBUTING.md

Contributing ...

... is cool and helps to make the 🌍 a better place 🤩

Installation

Requirements

• node >= 10.16.0
• yarn >= 1.7.0
• docker >= 23.0.0
• docker compose >= 2.16.0

Setup

Styleguide

1. yarn - Install all dependencies
2. yarn start - start the styleguide & live assets compilation.
3. View the styleguide http://localhost:4000

WordPress

1. Add the required proprietary plugins polylang-pro, advanced-custom-fields-pro, searchwp, searchwp-polylang into wordpress/wp-content/plugins.
2. yarn wp:init - Install WordPress with all dependencies
3. View your Site http://localhost
4. Site backend http://localhost/wp-admin - login: admin, password: admin

Contact us if you need help installing Advanced Custom Fields Pro, Polylang Pro and SearchWP.

Use

1. yarn start - start the styleguide & live assets compilation
2. yarn wp:start - start WordPress

Access

• Website: http://localhost
• Website backend http://localhost/wp-admin - login: admin, password: admin
• Phpmyadmin: http://localhost:8181
• Styleguide: http://localhost:4000
• Mailhog: http://localhost:8025

That's probably all you need to know! 🍻

Detailed Guide

Debug

XDEBUG is enabled by default.

• Setting the PHP constant SUPT_FORM_ASYNC to false (e.g. in wp-config.php) processes form mails and crm saving synchronously and thus facilitates debugging.
• Setting the PHP constant LES_VERTS_FORM_DEBUG_LOG to true (e.g. in wp-config.php) will log all form submissions and crm saving to ./form.log.

Theming

Templating

We use Timber to handle the templating. The theme "les-verts" is based on Timber Starter Theme.

Assets / styleguide

The assets are generated with our standard styleguide stack (see ./wordpress/wp-content/themes/les-verts/styleguide). To keep it as light and simple as possible, the docker image doesn't take care of the styleguide and assets pipeline.

Develop

The styleguide (fractal) and WordPress share the same assets build folder, which is in ./wordpress/wp-content/themes/les-verts/static. Check ./wordpress/wp-content/themes/les-verts/README.md for more details.

WordPress tools

WP-CLI

You can run any command with docker exec, for example: docker exec wp_docker_les_verts wp theme install Akismet

Official docs: https://wp-cli.org/commands/

List installed plugins

• docker exec wp_docker_les_verts wp plugin list

Update plugins

• List needed updates: docker exec wp_docker wp plugin update --all --dry-run
• Update all plugins: docker exec wp_docker_les_verts wp plugin update --all
• Update a single plugin: docker exec wp_docker_les_verts wp plugin update <pluginname>

Install a plugin

• docker exec wp_docker_les_verts wp plugin install <pluginname> --activate
• OR add a submodule in ./wordpress/wp-content/plugins if needed. If you know what you're doing.

More

See https://wp-cli.org/commands/plugin/

ACF & Custom Post Types

We use ACF to add custom fields on post types (& elsewhere).

Add a post type

1. Register a new post type class that extends the class \SUPT\Model located in theme/lib/post-types/Model.php
2. Include it in the loader file: theme/lib/_loader.php

ACF - Advanced Custom Fields

To version, share and deploy the ACF fields we created, we use the feature called Synchronized JSON. Basically, it means we have nothing to take care of manually. A typical flow is:

Add/edit fields

1. Edit the fields as you want in the backend
2. They are automatically saved in the folder theme/acf-json, nothing to do here
3. When you commit, don't forget to commit these files as well

Sync all fields

By default, when the acf-json folder is present, WordPress loads the ACF config from there, so it's always in sync. If you want to edit them in the backend though, wp will show "Available for sync". You can click manually "sync".

Useful commands

• yarn start - Start the Styleguide
• yarn wp:start - Start WordPress
• yarn start:all - Start both the styleguide and WordPress
• yarn build - Build the styleguide assets for production.
• yarn fractal:build - Build the styleguide as a static site in ./wordpress/wp-content/themes/les-verts/styleguide/dist/build
• yarn fractal sass:generate - auto-update the _loader.scss file with existing components
• yarn wp:init - Initialise the local WordPress instance
• yarn component:add type component_name - Create a new component for the styleguide.

L10n

Localization is a mess:

• We use Polylang Pro for content translation
• Follow these 99 simple steps for translating the theme 😅
  • Respect WordPress Internationalization on development
  • If you changed some ACF fields: Export all ACF field groups as PHP and store them in wordpress/wp-content/themes/les-verts/acf-translate.php. Make sure you don't overwrite the die(); statement on top.
  • Download and install Poedit Pro on your local machine. You need the pro version because of twig.
  • Open wordpress/wp-content/themes/les-verts/languages/theme.pot with Poedit Pro and choose Update from code. Save the updated theme.pot file.
  • Commit the theme.pot file and push it to the dev branch on github.
  • The new strings are pushed to crowdin by the l10n.yml workflow.
  • Translate the strings on crowdin.
  • Trigger the l10n.yml workflow again. This will download the translated strings from crowdin and create a new PR with the translated files. If no translations changed, no PR is created.
  • Merge the PR.