/best-practices

P'unk Ave development best practices.

🙏🙏🙏

How to add to this repo

  • Discuss topic with group during regular developer meeting or open a GitHub issue to begin discussion
  • If discussed during the meeting, someone on the team should capture notes in a GitHub issue discussion and supply a few code examples for further "offline" discussion
  • The developer responsible for the topic creates a pull request to this repo with changes or additions reflecting the consensus of the group

Our Guiding Pricipals

We use these as a lens with which to examine potential best practices:

  • Elegance - We design and build beautifully elegant applications and websites, this beauty should extend to the codebase as well.
  • Speed - We move quickly. We hit our milestones. We ship.
  • Pragmatism - We are pragmatic in our solutions. We don't over-engineer things. No reinventing the wheel. No yak shaving.
  • Maintainability - We maintain relationships with projects over years. This means we write maintainable code: well organized, well documented, well supported.
  • Innovation - We look for opportunities to experiment with emerging technologies and techniques. We learn.

Also see the Pragmatic Programmer Quick Reference Guide for additional rules to code by.

Table of Contents

Instead of having our content buried in folders, I'm proposing we pull the majority of it out onto this main README page. Below, I have built out a table of contents suggesting the topics we should cover with a few breif sentences and some code examples. Under some topics/sections, I started to bullet out points we might want to cover.

House Style Rules

Setting up a new project

Front-end Styleguides

Responsive

Collaborative Coding

Special topics

Here, we would link into specific articles with more in-depth information

Javascript

  • nest things in apos events where applicable
  • never attach anything to the global namespace
  • use data attributes for js selectors
  • use .find to keep your jquery scopes tight
  • be good at async

Markup

  • html 5 elements like header, footer, etc.
  • when to use divs, spans, uls, you should know this

Sizes

  • rems, ems, px, %, when to use what

Naming less variables

  • general to specific
  • use names like brand-primary and brand-secondary for colors

Our Grid

Setting up a new project

Using Apostrophe CLI / client boilerplate

Importing the final launch checklist

Setting up package.json

  • including dependencies
  • configuring start script npm start vs node app

Setting up app.js

  • shortnames
  • security
  • other config stuff

Project folder structure

  • components / macros
  • pages
  • less
  • client-side js

Naming modules

Front-end Styleguides

???

Responsive

Mobile

  • The bare minimums
  • naming your breakpoints
  • where to put responsive styles

Cross Browser

  • The bare minimums
  • Tools we use for testing

Accessibility

  • The bare minimums
  • Docs for WCAG etc.

Collaborative Coding

Git Workflow

TODO: Locking down master

Some basic rules to follow when developing on teams:

  • Anything in the master branch is deployable
  • To work on something new, create a descriptively named branch off of master (ie: feature/new-oauth2-scopes)
  • Commit to that branch locally and regularly push your work to the same named branch on the server
  • When you need feedback or help, or you think the branch is ready for merging, open a pull request
  • After someone else has reviewed and signed off on the feature, you can merge it into master
  • Once it is merged and pushed to master, you can and should deploy immediately

The above list is from the article GitHub Flow by Scott Chacon

To get a new feature branch started:

git checkout master
git pull origin master
git checkout -b feature/my-feature-branch
... write lots of code, many commits ...

When you are ready to have code reviewed:

git checkout master
git pull origin master
git checkout feature/my-feature-branch

If this is a new branch and it hasn't been previously pushed you may ...

git rebase -i master

This will allow you to squash and clean up your commits before code review for easier diffs/discussion ... otherwise ...

git merge origin master

Then ...

git push origin feature/my-feature-branch

Then create a PR in github.

Once you are done with the code review, time to merge onto master!

Branch Naming

prefix/descriptive-branch-name

Prefixing

hotfix - quick fix which will be merged directly into master, bypassing the review process

feature - branch for building out a new feature, goes through normal review process before being merged into master

fix - fix to be optionally merged into staging branch for deployment to staging for testing before being merged into master for deployment