This document covers the following information about the repo itself. For technical specifications for this project, see README.md:
The development strategy for this project was to create a back-end agnostic front-end site which interfaces with a CRUD-based CMS via a REST API. The front-end was developed with VueJS v3 and the back-end is a Rails 7 application. The front and back ends are relatively independent of each other and either could be switched out for another technology e.g.: the back-end could just as easily be node, python, php, etc.
The project is deployed to Heroku.com, however that too could easily be replaced by another hosting service.
The front-end was developed first; the relevant branches which cover these phases are staging and production. Both of these branches are currently deployed to their respective environments. The content for the site is stored as embedded JSON and was structured to be representative of the way the back-end would ultimately provide the content. This JSON content is embedded within each Page's respective .vue component (app/javascript/pages/website/**.vue).
The exceptions to the embedded page content are:
- The various articles displayed on the "Newsroom" page, as well as the individual articles themselves, which are pulled from the back-end via the
ArticlesController. - The list of tests on the "Test Directory" page, as well as the individual Test pages themselves are pulled from the back-end via the
TestsController - The other portion of the front-end which is connected to the back end is the processing of the "Contact Us" page, which is processed by the
ContactsController.
REST/CRUD communication between the front & back ends is facilitated by the /app/javascript/apis/**.ts, /app/javascript/services/**.ts, and /app/javascript/stores/**.ts files.
The back-end, CMS development is incomplete. The various iterations of development for the back-end are available in the three categorized branches outlined below. WARNING: With the exception of staging & production, all other branches should be considered as "works in progress" and have varying degrees of functionality and should not be merged into staging or production directly and without a thorough review of each individual branch. Theses additional branches are provided for reference only. See the "Branch details" section for specific information about each branch.
The branch naming convention is as follows:
- Top-level branches have a single name without a prefixed, slash delineated category and are aligned to their respective deployment environment names
- Categorized branches are formatted as "category/descriptor". Commonly used categories are:
feature/– Denotes a specific feature which usually has a matching JIRA ticketrefactor/– Denotes a restructuring or cleaning up of an existing feature or functionalitybug/– Similar to afeatureand should have an accompanying JIRA ticketwip/– Denotes an experimental or otherwise incomplete codebase. Generally this is used as for proof-of-concept or experimental changes or otherwise a "save state" type backuptemp/– Denotes a branch which may be used to temporary store code when resolving conflicts, doing diffs, etc. They deleted once their immediate need has been metmerge/– Denotes a branch used to safely merge other branches prior to commits or pull requests
The way I have approached the branch management workflow generally aligns with the following:
- Create a new categorized branch from a top-level branch
- Make local changes, then commit and push the categorized branch
- If necessary, spin up a new deployment environment and push categorized branch to test
- Merge/Pull request the categorized branch into
stagingfor new changes (orproductionfor bug fixes) - Deploy updated top-level branch to respective environment
- Prune/delete categorized branch
production should be 1:1 with what is deployed to the Production environment
The master branch is used primarily as a "save state" for production, meaning that it coincides with the previously deployed version of the production branch. The reasoning behind this approach is that often times developers develop the muscle memory of typing "git push origin master" when they likely meant to push to another, more specific branch. This also keeps the branch names in line with their respective deployment environments.
The production branch encompasses all of the approved JIRA tickets and is the branch which, as of this writing, is currently deployed to the Production environment. production is considered a "clean" branch.
The staging branch includes the production as well as the notable addition of the "login" main menu items (see: https://base10.atlassian.net/browse/RBW-222) as well as various other minor changes. As of this writing, the staging branch can be merged into the production branch as soon as the portal login links outlined in the RBW-222 ticket are active/available. staging is considered a "clean" branch.
The training branch is stale and not in use. It was originally created for the technical training sessions on 2022-12-13 & 2022-12-15. There are a few changes which were made during those training sessions in order to illustrate various aspects of training, however those changes are not relevant for the staging nor production branches.
The refactor/unified-component-architecture is the most advanced branch and represents a significant divergence from the other branches. The idea behind this branch was to refactor various components, naming schemas, and data structures in an effort to create a more cohesive and dynamic codebase. This included changes such as renaming components (e.g.: AdjacentImageCard.vue to CardItemImageAdjacent.vue), reconfiguring "List" and "Item" parent/child components to follow a standard data structure, etc.
The goal of these changes was to streamline the transcribing of embedded JSON page data to rails seed files as well as using common model/controller/serializer structure for passing data between the front & back end. The Home page represents that proof-of-concept for this refactor, however all other pages still need to be reconnected with the new architecture as well as troubleshooting their respective seed files in /db/seeds/**.rb.
Please note that this is a very rough proof-of-concept – that being said, I do believe that this direction was the correct course of action and will ultimately yield a more concise and cohesive system. One major and painful realization which came with this branch is that neither the original FastJSON nor the Blueprinter serializer paradigms will be viable long-term solutions without significant changes to the JSON data structure, as well as the Vue components which depend upon that structure. Ultimately, I think the best course of action would be to use ActiveModelSerializers which has similar functionality to FastJSON & Blueprinter, but is significantly more flexible in how one can structure data for serialization; This includes the ability to combine data models with custom serializers which will likely be necessary for the Newsroom page which combines both page.rb, section.rb, & article.rb model data, but without an association between those models (essentially the copy for the page is provided by the page.rb & section.rb models, which are associated, while the list of articles is handled by the article.rb model and should be page agnostic). Another possible solution would be to create a page_articles join table, however setting that up and getting it to work well within a CMS would be a significant amount of work. Using a custom serializer is a more expedient solution.
The wip/cms branch consists of code demoed to RenegadeBio on 2023-01-10 where proof-of-concept CMS functionality which allowed a user to log in, via /sign_in. Once signed in, the user is able to edit CopyBlock.vue components directly inline with the TinyMCE editor by clicking directly on any copy block element which then loads the inline editor. Once editing is complete, the user clicks the "Save" button in the editor toolbar with submits the data to the CMS. This demo also included editing of CopyBlock models via the CMS interface using the more traditional form method. Only the copy_blocks_attributes content contained in the various db/seeds/**.rb files, which has been populated in the database is editable in this branch. This is mostly the content for the Home page, Tests, and Articles. This branch should be the closest common denominator between the staging & production branches and the other categorized, CMS relevant branches.
The feature/cms is an earlier iteration of the wip/cms branch. It is stale and not in use. The feature/cms branch and the wip/cms branches diverged due to a bug that arose which ultimately was caused by an issue with NPM packages which took a ridiculous amount of time to track down. Ultimately the easiest solution was to revert to a local backup of the previously working node_modules directory. Due to time constraints, I did not devote additional effort to resolving the issue once reverting to the previous node_modules directory proved successful.
I've uploaded the current/working version of the node_modules directory here in the event that the offending package(s) are still broken when downloaded via yarn install.
Once resolved, I moved forward with the wip/cms branch and abandoned this one. It can likely be deleted but is included for reference.
See Renegade CMS outstanding functionality Google Doc.
- Remove
blueprintergem and switch toactive_model_serializers