Phoenix Architectural Approach & Best Practices

Phoenix Architectural Approach & Best Practices.md

Development

General

We prefer code that's more readable and easier to understand over code that's concise or obfuscated. We spend time thinking about the most understandable variable names in their respective context, and even favor longer, easier to understand variable names over abbreviated ones.

We also prefer DRY code, and favor small, single purpose functions over long functions that try to do too much.

Pull Requests

When merging PRs, make sure to use the "Squash and merge" options so that all commits are squashed into a single commit for what the PR is doing:

After merging a PR, please make sure to delete the branch so that they are cleared from the list of branches for the repository.

PHP Code

Imports are organized in line-length order.

JS Code

Imports are organized in line-length order, with third-party package imports at the top of the file, followed by a line break and local project imports.

React Components

Initially when rapidly developing Phoenix (Next), we made some decisions on code file locations/hierarchy. Overtime we've come to refine this structure a bit, and are now working to update the Phoenix codebase with the latest decisions.

We want to update our code directory structure within the /components directory to follow this pattern:

- /components
  |_ /actions
  |_ /blocks
  |_ /pages
  |_ /utilities

Most of the standalone components residing as children of the /components should fall within one of the above children directories.

• /components/actions contains dispatchers for different actions.
• /components/blocks contains interface components that may match the interface components available in Contentful, or other components that show up as distinct stacked rows that build up a page.
• /components/pages contains components related to specific page types available on Phoenix.
• /components/utilities contains reusable items; they don’t have a “container” component and are typically used inside other components.

Process

Pivotal Tracker

The following outlines the stages of a ticket on the Team Rocket Board in Pivotal Tracker. The buttons on a ticket to Start, Finish, Deliver, Accept OR Reject will transition a ticket within the different stages.

⭐️ Feature OR 🐞 Bug Ticket

1. Planned: Ready for current iteration (also estimated if a feature).
2. Unstarted: No work has begun to address the ticket.
3. Started: Work has begun to address the ticket.
4. Finished: Work to address ticket is completed and a pull request has been submitted and awaiting review.
5. Delivered: Pull request has been merged.
6. Rejected: Reviewer (product manager or tech lead) has reviewed the work to address ticket and rejected it.
7. Accepted: Reviewer (product manager or tech lead) has reviewed the work to address ticket and accepted it.

⚙️ Chore Ticket

1. Planned: Ready for current iteration.
2. Unstarted: No work has begun to address the ticket.
3. Started: Work has begun to address the ticket.
4. Accepted: Work to address ticket is completed, pull request was submitted, reviewed and merged.