murindwaz / nifty-conventions

Code guidelines, general project requirements, and git workflow

nifty-conventions

nifty conventions is an opinionated set of conventions surrounding code guidelines, general project requirements, and git workflow for Rapid MVP's (namely for use in conjunction with Eskimo-based projects).

index

• code guidelines
• general project requirements
• git workflow
• license

code guidelines

• inherits @felixge's node-style-guide

• 2 spaces (no tabs)

• semi-colons *optional*

  • do use uglify for production deployments
  • do use jshint for checking missing semicolons and linting code (also use a .jshintrc file and share it in the repo with your team; make sure everyone has JSHint plugins on their IDE as well that consume this config file)
  • do not mix usage of semi-colons and no semi-colons

• use apostrophes instead of quotes (when possible)

• peer-review occasionally *optional for solo projects*

  • do review other's code when merging required
  • do comment on commits and follow-up if needed

• use pull requests when working with teams

• always return early (you don't always need brackets {})

  // good
  if (err) return next(err);
  
  // bad
  if (err) {
    next(err);
  }
  next();

• do not run into "callback hell"

• do not use unnecessary spaces (think how many times you'll be hitting SPACE; think of readability vs. time spent coding)

  // good
  if (foo)
    return getBar('good');
  
  // bad
  if ( foo )
    return getBar( "bad" );
  
  // good
  if (foo) {
    return getBar('good');
  }
  getBar('good-two');
  
  // bad
  if (foo) {
    getBar('bad')
  } else {
    getBar('bad-two')
  }

• see Git Workflow below

general project requirements

• use Eskimo for building the project ("Rapid MVP")
• Readme First Approach ("RFA") – start a "Readme.md" Markdown file and document the project's needs and scope before you begin. If you're writing an API, then document the API. If you're writing a web app, then document the web app's routes and core functionality.
  • spend more time thinking and researching than writing
  • create wireframes/sketches ("mockups") on paper/pen
  • do not waste time with extremely-detailed mockups
  • do not write run-on sentences
  • do not worry about punctuation or capitalization, (but be consistent with approach and style)
  • write succintly and cut out as many words as possible to make a point, save your reader time
  • use analogies when possible and use links everywhere
  • include an "Index" with links to anchors throughout the Markdown file
  • include a "License" and "Contributors" section
  • include a blockquote with a brief description of the project as an opener to the reader
• test-driven-development (and deployment) ("TDD")
  • Travis-CI
    • deployment using webhooks
      • use when your server is behind a VPN
    • deployment using ssh
      • do not use when your server is behind a VPN
    • do not allow deployment when builds fail
  • Coveralls and Istanbul
  • Mocha
    • do not use with gulp, use simply with npm script in package.json
  • Chai
    • use with sinon-chai
  • New Relic
  • Gulp
    • use a watch task - with live reloading of CSS/JS - with jshint
  • use zero-downtime deployments
• application environments
  • local – port 3000
  • server with node-http-proxy or nginx (with reverse-proxy) running on port 80 (see "server setup" bullet point below)
    • development ("dev") – accessible behind BasicAuth at a URL such as http://dev.project.com, port 3040, use unique DB, same server as production
    • staging ("stag") – do not use a staging environment for Rapid MVP's, it's overkill
    • production ("prod") – accessible at a URL such as http://project.com, port 3080, use unique DB, same server as development
• server setup
  • Ubuntu 14.04 LTS 64-bit
    • lock down your server heavily
    • do not allow root nor password-based log in attempts
    • do not require a VPN to connect to the server (should be end-user's responsibility for secure connection)
    • do create a new user per member on the team (and add their SSH public key to /home/${USER}/.ssh/authorized_keys
• development setup
  • text editor (one of the following) * vim (with zsh, oh-my-zsh, NERDTree and other plugins) *recommended* * Sublime Text (>= 2) * Atom
  • operating system * one of the following: - Linux Mint 17 LTS - Ubuntu 14.04 LTS - Mac OS X * do not use Vagrant and/or VirtualBox when possible * do not use Windows as a development environment
  • package management * if Mac OS X, then use brew and LaunchRocket * if Ubuntu, then use built-in apt-get
• server host
  • Digital Ocean – cheap and great for Rapid MVP's
  • Linode – lots of CPU's (great for Node's cluster module), but somewhat expensive
  • Amazon EC2 – lots of features, but expensive
• security considerations
  • use VPN when connected to public connections *or always*
  • do not share passwords/keys in repositories when possible
• use Jade for writing short-hand HTML
• use LESS for CSS and Bower for front-end package management
• use email-templates for emails along with Postmark for transactional email or Sendgrid for bulk email (be sure to enable DKIM/SPF signing)
• use Slate for API documentation
• use StatusPage for API status page hosting
• use Compose for MongoDB hosting
• use RedisToGo for Redis hosting
• use CDN-hosted assets on Amazon S3 and CloudFront
• write log files on server and use logrotate (and tail logs over SSH with tail -f /var/log/something.log)
• use upstart for node processes on the server
• use Amazon Route 53 for DNS hosting
• use Namecheap for domain name registration
• use Google Hangouts for team video chat
• use Slack for team chat
• use GeoTrust RapidSSL (cheap) or Digicert (expensive) for SSL security certificates in production *regardless if application handles financial transactions*
• use Stripe for payments

git workflow

1. read GIT Conventions

2. install git-extras (and set up git aliases)

3. edit and save changes to a file(s)

4. lint, test, add, commit, pull, and push changes

   # optional
   gulp jshint
   npm test
   
   # required
   git add --all
   git commit -m 'fixed opacity of header. closes #1'
   git pull
   git push

5. check to make sure builds pass and deploy changes (should be automatic with Travis-CI)

6. repeat steps 3-5

license

MIT