From 2c08a22a8e151db9f1d841e99a749ddacc195baa Mon Sep 17 00:00:00 2001 From: Luke Carl Hartman Date: Fri, 6 Sep 2024 16:37:47 -0700 Subject: [PATCH] medEng files you should not edit --- ...23-05-20-mediaengagement-technical-docs.md | 86 ++++++++++++++++++- _posts/2023-05-21-mediaengagement.md | 17 +++- 2 files changed, 99 insertions(+), 4 deletions(-) diff --git a/_posts/2023-05-20-mediaengagement-technical-docs.md b/_posts/2023-05-20-mediaengagement-technical-docs.md index 0732684..bc1e3d7 100644 --- a/_posts/2023-05-20-mediaengagement-technical-docs.md +++ b/_posts/2023-05-20-mediaengagement-technical-docs.md @@ -149,10 +149,94 @@ npm run watch npm run production ``` -# Coding +# Coding Guidelines A collection of general tips and rules of thumb when coding and building a project. +### Files you should not edit + +It’s important to understand that certain files and folders in your project should never be manually edited because they are automatically generated or managed by external tools. Editing these files can lead to confusion or cause your changes to be overwritten. + +#### 1. SCSS Output `.css` Files: + + - The `dist/css` files that are generated from your SCSS (Sassy CSS) are **output files**. These are created automatically when the SCSS code is compiled. + + - **Why you shouldn't edit them**: + + - These files are automatically generated by the SCSS compiler, and any changes you make directly to them will be overwritten the next time SCSS is compiled. + + - The SCSS files are your source of truth for styles. If you need to change styles, you should make the changes in the SCSS files, and then let the compiler generate the updated CSS. + + - Editing the compiled CSS leads to confusion, as future developers (or even yourself) won’t know where changes were made or why those changes aren’t reflected in the SCSS code. + + - **How to handle changes**: Always edit the SCSS files, not the compiled `dist/css` files. When you save changes, your build tools will regenerate the correct `.css` files. + +#### 2. `node_modules/` Files: + + - The `node_modules/` folder contains all the dependencies and libraries your project needs to run. These files are installed automatically when you run `npm install` and should never be edited. + + - **Why you shouldn't edit them**: + - These files are managed by npm. When you install or update packages, npm handles the contents of this folder. + + - Any manual changes made to files in `node_modules/` will be lost the next time you update your dependencies or reinstall them. + + - Making changes in the `node_modules/` directory can introduce bugs or security vulnerabilities because these packages are typically maintained by experienced developers and have been tested. + + - You shouldn't track `node_modules/` in your version control (e.g., Git). These files can be installed from `package.json` on any machine, so there's no need to modify or commit them. + +#### 3. `dist/` Folder: + + - The `dist/` folder is where your compiled assets (like CSS and JavaScript) are stored after running your build process. This folder contains **output files** and should not be manually edited. + + - **Why you shouldn't edit them**: + - The files in the `dist/` directory are automatically generated during the build process (via Webpack or Laravel Mix). Any manual changes here will be overwritten when you recompile the assets. + + - These files are not your source files; they are meant for use by the browser. If you need to change the behavior or styling, you should edit the source files located in `assets/js/` or `assets/scss/`. + + - **How to handle changes**: Make changes to the source files in the `assets/` directory, and then recompile your assets by running the build process (`npm run watch` or `npm run production`). + +#### 4. `mix-manifest.json`: + + - The `mix-manifest.json` file is automatically generated by Laravel Mix and maps your source files to their compiled versions. + + - **Why you shouldn't edit it**: + + - This file is generated every time you run your build process, and any changes will be overwritten. It's used internally by the build tools to manage your assets. + + - **How to handle changes**: Let the build process manage this file. You don’t need to make any manual changes. + +#### 5. `config.json`: + + - The `config.json` file is used to store local configuration (e.g., proxy URLs for BrowserSync) and is added to `.gitignore`, meaning each developer has their own version of this file for their environment. + + - **Why you shouldn't edit it globally**: + + - This file is meant for local development and contains environment-specific settings. Editing someone else’s config file can disrupt their development environment. + + - **How to handle changes**: Each developer should manage their own version of `config.json` and not edit it globally. + +#### 6. `.lock` Files (`composer.lock`, `package-lock.json`): + + - The `.lock` files (`composer.lock` for Composer and `package-lock.json` for npm) store the exact versions of dependencies that were installed when the project was last set up. These files ensure that everyone on the team is using the same versions of libraries and packages. + + - **Why you shouldn't edit them**: + + - These files are automatically generated and managed by Composer and npm during dependency installation. Manually editing them can lead to mismatches in dependency versions and cause build or runtime errors. + + - They ensure consistency across development environments, so everyone is using the same versions of libraries. If you need to change or update a dependency, use the proper package manager commands (`composer update` or `npm install`), and the `.lock` files will be updated automatically. + + - **How to handle changes**: Never edit `.lock` files manually. Use `composer` or `npm` to install or update dependencies, and these files will be updated accordingly. + +#### 7. `vendor/` Directory: + + - The `vendor/` directory is where Composer stores all of your project’s PHP dependencies after running `composer install`. + + - **Why you shouldn't edit it**: + + - This directory is automatically generated by Composer, and any changes made here will be lost the next time dependencies are installed or updated. + + - The `vendor/` directory contains third-party libraries that you depend on but do not control. These libraries are maintained by other developers, and making changes here could lead to unexpected behavior or security issues. + ## Best practices > #### Think about the performance impact of your code and solutions diff --git a/_posts/2023-05-21-mediaengagement.md b/_posts/2023-05-21-mediaengagement.md index 2d35e84..4ccd64b 100644 --- a/_posts/2023-05-21-mediaengagement.md +++ b/_posts/2023-05-21-mediaengagement.md @@ -213,7 +213,18 @@ Technical Docs - [Local development](/mediaengagement-technical-docs/#local-deve ## Coding Guidelines -For more in depth detail see [Technical Docs - Coding](/mediaengagement-technical-docs/#coding) +### Files You Should Not Edit in the Theme + +It’s important to understand that certain files and folders in the `engage-2-x` the should never be manually edited because they are automatically generated or managed by external tools. Editing these files can lead to confusion, break the site or cause your changes to be overwritten. + +1. **`dist/` Folder**: Contains compiled files. Do not edit them. +2. **`node_modules/` Folder**: Contains npm dependencies. Managed automatically. +3. **`vendor/` Directory**: Contains PHP dependencies, managed by Composer. +4. **`config.json`**: Each developer manages their own local version. +5. **`.lock` Files**: Managed by Composer and npm, don't edit manually. +6. **`mix-manifest.json`**: Automatically generated, no need to change. + +For more in depth detail see [Technical Docs - Coding Guidelines](/mediaengagement-technical-docs/#files-you-should-not-edit) ### Best Practices @@ -255,8 +266,8 @@ For more in depth detail see [Technical Docs - CSS](/mediaengagement-technical-d ## Theme Structure Engage uses the **Timber** framework and **Twig** templating engine. Familiarize yourself with: -- [Timber Documentation](http://timber.github.io/timber) -- [Twig Documentation](https://twig.symfony.com) +- [Timber Documentation](https://timber.github.io/docs/v2/) +- [Twig Documentation](https://twig.symfony.com/doc/3.x/intro.html) ---