## MegaCalendar WordPress Plugin ##

This repository houses the [MegaCalendar WordPress Plugin](https://wordpress.org/plugins/megabase-calendar/) devlopment repository.

If you are looking for the jQuery event calendar plugin, click [here](https://bitbucket.org/musicidb-dev/megacal-event-calendar/src/main/) 

---

### Project Setup ###

**Requirements:**

- PHP >= v7.4
- NodeJS >= lts/fermium (14.17.0) 
- Git

#### First time setup ####

- Clone project from repository
- `cd /path/to/repo/`
- `npm install`
- `npm start`

---

### Development Process ###

#### PHP Development ####

If you intend to develop using the Production database, you can simply install the Plugin via one of the methods outlined below and start your development.

To connect the plugin to the Staging database for a feature not yet released to Production, to test high-impact functionality, or to test risky functionality, you can follow the steps below. 

##### Connect to Staging Database #####

To connect to the Staging database, add a file named `.env` to the root Plugin directory containing the following:

```
MEGACAL_API_BASE="https://x3xsukmpeb.execute-api.us-east-1.amazonaws.com/release"
MEGACAL_API_KEY="kBqxgGbtTwPC2S27uwz56QOKRrhn2Hf66tAdWRF0"
```

To switch back to the Production database:
- Remove or rename the .env file
- Use the Account Reset button to unlink your Staging account
- Link or Create a Production Account
- Flush Event Cache

For active development, you have 3 options:

##### Local Development via wp-env #####
---

This is the most configuation-free way get a clean, local version of the plugin up and running. However, it requires [docker](https://www.docker.com) to be installed and configured on your machine before it can be used. If you have issues with docker, skip to the next section. 

After running through the first-time setup outlined above, you can use the follwing commands to create, start, and destroy local environments for testing.

```bash
npm run setup-wp 	# Create a new WP environment from scratch
npm run start-wp 	# Start your WP environment
npm run stop-wp  	# Stop your WP environment
npm run teardown-wp # Teardown and Destroy your WP environment
npm run clean-wp	# Clean up any orphaned containers
```

The local environments will be created using docker containers, and are all managed with [wp-env](https://www.npmjs.com/package/@wordpress/env). If you need more granular control, a passthrough script has been created. You can use that as follows:

```bash
npm run wp-env -- --arg1 --arg2
```

##### Local Development via Local/Apache #####
---

You can set up your own local server to host a local site. 

The simplest way to get started down this path is to install [Local](https://localwp.com), and set up a clean WordPress installation, and clone the plugin repository directly into the plugins folder of that site. 

If you choose to configure IIS/Apache/Nginx locally, this document assumes you have the knowledge to do so on your own. 

##### Remote Development on Staging/Dev Site #####
---

If you have a remotely hosted site on which you can test, this is also an option. Make your changes locally, and upload them as you go.  

This approach is recommended as a last-ditch effort, as it is the least efficient and may result in issues with partially deployed features, and/or the site being out of sync with your local working directory. 

To make these occurrences less likely, you can package and re-upload the entire plugin for each change, but this will increase your development time. 

#### Scripts, Sass, & CSS ####

This project uses node to build scripts and compile scss. Make sure you run `npm install` before attempting to build the assets. 

##### Local Development #####
---

When developing locally, you can simply run `npm start` in order to watch files for changes, and build scripts/styles in real time. A page refresh will be required to see your changes.

**BrowserSync**

If you are working locally with wp-env, you can run:

```bash
npm run start-wp
npm run start-with-browsersync
```

This will start your local WP environment, and then will watch for file changes. Browsersync is pre-configured to reference the wp-env environment url, and your browser will automatically refresh with every change.

If you are running locally but not via wp-env, and you want to use browsersync, you can update `gulpfile.js` and change the `proxy` setting for browsersync to point to your local url. If you do this **DO NOT** commit your own local url.

```javascript
browserSync.init({
	files: ['./**/*.php'],
	proxy: 'localhost:8888', // <--- Update this url
});
```

##### JavaScript #####
---

All JavaScript source files are located in `assets/src/js/`.

Within the source directory, there are 3 subdirectories:

**admin**: All scripts in this directory will be combined into `admin.min.js`, and loaded on the WP admin dashboard.

**main**: All scripts in this directory will be comined into `main.min.js`, and loaded on the frontend.

**vendor**: All scripts in this directory must be manually included via `main_scripts` or `admin_scripts` in `gulpfile.js`. This is done to maintain correct script loading order, and prevent loading vendor scripts where they aren't needed. All vendor scripts should be pre-minified. 

---

All compiled JavaScript files are located in `assets/build/js/` - Sourcemaps are in `assets/build/maps/`.

There are 2 files located here:

**admin.min.js**: Loaded on the WP admin dashboard

**main.min.js**: Loaded on the site frontend

##### Sass/CSS #####
---

All stylesheet sources can be found in `assets/src/scss/`

Beneath this directory there are:

**admin**: Admin-facing SCSS files should be stored here. Admin-only vendor files can be placed in the `admin/vendor/` directory.

**front-end**: Frontend-facing SCSS files should be stored here. 

**vendor**: Vendor SCSS files should be stored here. Vendor CSS should be unminified SCSS. Since regular CSS is valid SCSS, you can use CSS, but the file must have a `.scss` extension.

**admin.scss**: Contains imports for the admin stylesheet

**styles.scss**: Contains all imports for the frontend stylesheet

---

All compiled css files are located in `assets/build/css/` - Sourcemaps are in `assets/build/maps/`.

There are 2 files located here:

**admin.css**: Loaded on the WP admin dashboard

**styles.css**: Loaded on the site frontend

##### Images/Fonts/Other Assets #####
---

Images are stored in `assets/img/`

Fonts are stored in `assets/font/` 

Any additional assets added in the future can be added to their own directory below `assets`

In scripts/stylesheets assets can be accessed using the relative path, such as `../assets/img/filename.png`

### Git ###
---

The plugin is released to the WordPress repository on a somewhat regular cycle. Generally, every 2-3 weeks.

In order to ensure that the code is high quality, the release has been reliably tested, and production bugs are minimized, please use the following guide to determine the best course of action:

**New Features & Non-Urgent Bug Fixes**

***Includes: New functionality, existing functionality change, large-scale script or style refactors, visual or functionality bugs that DON'T greatly impede usability or cause technical issues***

Any update should begin with a feature branch based off of `main`. 

Naming convention for a feature branch is `feature/descriptive-name`. For example: `feature/implement-account-management` or `feature/refactor-frontend-styles`

Naming convention for a bug fix branch is `bugfix/descriptive-name`. For example: `bugfix/conflict-with-gravityforms` or `bugfix/ios-style-fixes`

During development, you should regularly merge `main` into your feature branch, to avoid dealing with conflicts later.

After implementation is complete and you have tested your own work thoroughly, you should create a Pull Request in BitBucket and assign another developer to review and approve.

Your PR's name should be the name of your feature branch, and the description should include:

- A summary of the goal, and a link to any relevany Infinity tickets
- A clear list of changes
- Steps to test the update

**Urgent / Hotfixes**

***Includes: Visual or Functionality Bugs that DO greatly impede usability or cause technical issues***

If a release is planned within a few days of your change, please make sure to post a heads up in the MegaCalendar channel in Slack and tag `@channel`.

There will undoubtedly be instances of serious bugs being released to Production, and generally these will need to be dealt with quickly and efficiently. 

This is a case where the release cycle can be broken, and the PR process can be skipped. However, for the best chance of a successful fix the process should be as follows:

- Tag `@channel` in the MegaCalendar Slack channel and alert everyone there is a major production bugfix being worked
- Create a bugfix branch to work on, until your fix is ready for release 
- When possible, work locally or on a Staging site to resolve and thoroughly test the fix
- Tag another developer and ask them to give your branch a quick test
- After getting one other person to test and sign off on the fix, merge directly to `main` and coordinate release via the MegaCalendar Slack channel 

**Minor Updates / Small CSS Tweaks**

***Includes: Any change that is 1 or 2 lines of code, has a low-risk impact to Production, and can be reviewed and understood quickly or immediately.***

If a release is planned within a few days of your change, please make sure to post a heads up in the MegaCalendar channel in Slack and tag `@channel`. 

Sometimes the feature branch & PR process is overkill, especially when you just need to make a minor change. For example: You need to change `padding: 20px` to `padding: 25px` on a single button.

In these situations, you should ask yourself the following questions:

- Is there a release happening tomorrow?
	- Yes: Tag whoever is managing the deploy in Slack *before* commiting to `main`, and make sure they have time to review and test the release
	- No: Go ahead and commit directly to `main` and tag whoever is managing the deploy in Slack to give them a heads up

- Am I making *many* small changes?
	- Yes: Make a feature branch, and go through the approval process please. 100 small changes = one big refactor.
	- No: Just a couple of small changes is fine, commit directly to `main`, give a heads up in Slack, and **make sure your commit messages clearly state what changed** 

- Is this change risky?
	- Yes: Make a feature branch, and go through the approval process please. Risky changes include functional changes, very general css changes (think globally setting a border on root `img` tags), or many changes across many files
	- No: Just a couple of small changes is fine, commit directly to `main`, give a heads up in Slack, and **make sure your commit messages clearly state what changed** 

### Deployment & Packaging Releases ###
---

Packaging a release is done using an npm script, and depends on git to create the package.

#### Packaging a Test / Preview Release ####
---

To create a zip file for uploading to your Staging site, or to provide a user with a preview release, you can use the package script.

Simply change to your working directory, checkout the branch that you want to create a package for, and run `npm run package`.

```bash
cd /path/to/local/repo
git checkout feature/preview-branch
npm run package
```

By default the zip file will be after the current verion, like `megabase-calendar-x.x.x.zip`, and will be placed into the Plugin root folder. If you want to create a zip file with a special preview version suffix, you can pass the `package-version` flag.

```bash
cd /path/to/local/repo
git checkout feature/preview-branch
npm run package -- --package-version="1.2.3-beta"
```

The above will generate a file named `megabase-calendar-1.2.3-beta.zip`.

#### Deploying to the WordPress Repository ####
---

Releases are stored in [WordPress' SVN Repository](https://plugins.svn.wordpress.org/megabase-calendar/).

For more information on setting up the SVN repository on your local machine, review the [documentation](https://developer.wordpress.org/plugins/wordpress-org/how-to-use-subversion/).

The SVN repository does not mirror this Git repo, it reflects only final releases of the Plugin.

##### Pre-Deploy #####
---
Before packaging a release, run through the following steps:

- Make sure you've checked out `main`, and you don't have any commits that have not been pushed
- Run `npm run build` to build assets for Production
- Update the version number in `class-megabase-calendar.php`, `readme.txt`, and `gulpfile.js`
- Review commit log and add a user-friendly list of changes in the Changelog section of `readme.txt`. Most recent versions should be at the top of the Changelog.
- Commit & push your version & readme changes
- Note the last commit hash & tag the commit with the version number: `git tag -a vX.X.X <commit_hash> -m "vX.X.X release"`
- Push your tag: `git push --tags`

##### Deploy #####
---

Packaging for a deploy is relatively simple. If you have completed all pre-deploy steps, simply run `npm run package` from your local repo and the versioned zip file will be saved to the Plugin root.

Once you have the release package, run through the following steps:

- Navigate to your local svn directory
- Navigate into `trunk/`, and remove all files
- Open the zip file and navigate into the `megabase-calendar/` directory
- Extract all files from the `megabase-calendar/` directory into `trunk/`
- Close the zip file
- Copy all files from `trunk/`
- Navigate back up to the svn directory
- Navigate into `tags/`
- Create a new folder named for the current version number
- Paste copied files into the new version directory
- Manually copy any new files from the `screenshots/` directory in your local git directory into `assets/` inside of the svn directory
- In SmartSVN
	- Select all `Unversioned` files and click Add
	- Afer adding is complete, select all files and click Commit
	- Enter a commit message in the following format for the current version: "vX.X.X Release" and click through to commit

##### Post-Deploy #####
---

After a successful commit, run through the following steps:

- Confirm new version number is appearing on the [WordPress repo page](https://wordpress.org/plugins/megabase-calendar/)
- Confirm no issues with update via WP Plugin screen
- Confirm no issues with new installation from WP Plugin screen

<!-- ### Other Notes ### -->
<!-- --- -->

---
#### Brian Notes ####
---

##### Gulp styles and js MegaCalendar WordPress Plugin #####
```bash
cd "C:\`Megabase DEV\Internal\MegaCalendar\Plugin\repo"
npm start
```

##### Create zip package from REPO (all local commits) #####
Commit to Repo

```bash
cd "C:\`Megabase DEV\Internal\MegaCalendar\Plugin\repo"
npm run package
```

Outputs to : C:\`Megabase DEV\Internal\MegaCalendar\Plugin\repo > megabase-calendar-x.y.z.zip


##### Style Tooltip Pop-up #####
mega-tooltip - disable display none