Skip to content

Latest commit

 

History

History
261 lines (185 loc) · 9.44 KB

development_practice.md

File metadata and controls

261 lines (185 loc) · 9.44 KB

Development Practice

Routine / Project work

Selecting an issue

Each week we either work from the Sprint Board The Sprint Backlog column of a given board has issues ordered roughly by priority. Always assign yourself to an issue before to starting to work on it, and move it to the in progress column.

Pairing

Our team considers ourselves "pairing-friendly." Several of us very much like to pair, and we all do pair at least sometimes. Feel free to ask anyone to pair with you if you would like help or just want some company to work on an issue.

If a PR is submitted by the pair, they can merge it themselves without code review. The idea is that code review has happened during the process of development with a pair. They can still request review if they'd like another opinion.

Some recommended reading:

Checklist for every time you pair:

  • Use an editor where you can both see the outline of the project.
  • Turn on absolute line numbers.
  • Agree on task, scope, and intention.
  • Set a timer. Remember to take breaks and swap drivers.
  • Keep the chat going. If you're driving, narrate what you're doing.
  • Use Co-authored-by lines in the commit message (This .gitmessage file might be handy)
  • Check in afterwards about how it went.

Submitting code

  • Ensure code is arranged in logical, unitary commits unless you want it squash-merged.
  • Ensure any new or modified code has test coverage. Many of us practice test-driven development, but at the least a test should be confirmed to be failing before the code change is applied.
  • Run Rubocop to enforce code style agreed upon by our team.
  • Open a pull request in Github
    • Reference the relevant issues, using github keywords if the issue will be resolved
  • Make adjustments as-needed according to code review.
  • If your PR isn't getting reviewed, freely post it in slack.
  • If your PR is approved and passes CI checks you may merge your own pull request. Usually this happens when it's reviewed before CI is finished.
  • If this code was developed in a pair and passes CI checks, you may merge without waiting for another reviewer.
  • Ensure the issue is closed if no further work is required.

Reviewing code

  • Review other pull requests over the course of the day.
  • We generally follow the Samvera Code Review guidelines
  • Ask the author of the code to pair with you on the review if desired / required.
  • We generally want code to be merged, but feel free to ask questions about code you do not understand.

Dependabot

We have set up our github repositories to use Dependabot, which generates PRs to upgrade dependencies based on security warnings. Based on our experience with these PRs it is important to test a deployment to a staging server before merging them even if the tests are all passing. Also, in some of our projects our tests do not fully cover our javascript code. In those cases when javascript dependencies are updated it can be helpful to do a bit of QA before merging.

If the PR has been open for a while, or you've just merged another PR, use the @dependabot rebase comment to trigger a rebase before deploying. This can take a few minutes.

Ruby Documentation (Using YARD)

Code documentation is implemented for Ruby code bases using YARD, a Gem which parses Ruby source code file comments and generates documentation in the HTML.

Installing the Gem

$ bundle add --group "development" yard

YARD Tags

YARD using a system of tags invoked from within the comments of a source code file by prefixing the tag keyword with the @ character. The comprehensive list of tags is available here.

Examples

For documenting class implementations, one may look to the following example for guidance:

# @class My Class Description
class MyWebServer
  # @!attribute state
  #   @return [Numeric] the number of POST requests received by the server
  attr_accessor :name

  # Handles a request
  # @param request [Request] the request object
  # @param [Hash] opts the options to create a message with.
  # @option opts [String] :foo The foo argument
  # @option opts [Array<String>] :bar The bar argument
  # @return [String] the resulting webpage
  def get(request, opts = {})
    "GET request received"
  end

  # (see #get)
  # @note This method may modify our application state!
  # @param (see #get)
  # @return (see #get)
  def post(request, opts = {})
    @state += 1
    "POST request received"
  end
end

Generating YARD Documentation

Please generate the documentation with the following invocation:

$ bundle exec yard doc
$ open doc/index.html

Styling with Prettier

Prettier is a tool used for enforcing source code and configuration formatting standards.

In order to integrate Prettier into any given project, the following are required to already be installed in your project:

Installing Prettier

yarn add -D eslint-config-prettier
yarn add -D prettier eslint-config-prettier

Configuring Prettier

Prettier configuration options are set within a YAML file .prettierrc, which should be located at the root path of the project.

The following configuration defines a default minimal configuration which prefers double quotes to single quotes:

singleQuote: true
overrides: []

More information on Prettier configuration can be found within the documentation.

Configuring Prettier to Ignore File Paths

Please note that, by default, Prettier looks to enforce formatting standards for all files within the project. In order to ensure that files are not checked, one can create a file .prettierignore:

.yarn/
vendor/

This is a common set of file system patterns which ensure that files within the .yarn and vendor directories are explicitly ignored by Prettier.

Checking for Prettier Formatting Violations

The following checks for any violations of the Prettier formatting rules:

yarn run prettier . --check

Automatically Correcting Violations

One can also attempt to fix any violations found by Prettier with the following:

yarn run prettier . --write

Linting JavaScript with ESLint

ESLint is a tool used for enforcing specific code formatting standards for JavaScript and TypeScript.

For integrating ESLint into any given project, both Node.js and Yarn are required (as was the case with Prettier).

Installing ESLint

The following will ensure that ESLint is installed and that the default configuration options used by AirBNB will be applied to the project:

yarn add -D eslint eslint-plugin-import eslint-config-airbnb-base eslint-config-prettier

Configuring ESLint

ESLint configuration options are set within a file eslintrc.config.mjs, which is located at the root path of the project.

The following configuration inherits the default options from airbnb-base and ensures that there are no conflicts between ESLint and Prettier:

import globals from 'globals';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import js from '@eslint/js';
import { FlatCompat } from '@eslint/eslintrc';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const compat = new FlatCompat({
  baseDirectory: __dirname,
  recommendedConfig: js.configs.recommended,
  allConfig: js.configs.all,
});

export default [
  ...compat.extends('airbnb-base', 'prettier'),
  {
    languageOptions: {
      globals: {
        ...globals.browser,
      },

      ecmaVersion: 'latest',
      sourceType: 'module',
    },
  },
];

Please know that the documentation for the ESLint configuration options are also publicly available.

Ignoring Source Code Files

ESLint provides one with the ability to ignore file system patterns within the configuration file with the following:

export default [
  {
    ignores: [".config/*"]
  }
];

Please see the documentation for more details.

Linting Source Code Files with ESLint

The following lines all source code files using ESLint. By default, the eslint.config.mjs file is used for the configuration:

yarn run eslint

Automatically Correcting Violations

One can also attempt to fix any linting violations found by ESLint by invoking the following:

yarn run eslint --fix

Adding ESLint and Prettier to CircleCI

Within the CircleCI configuration file, one can add the following:

- run:
    name: Lint using ESLint
    command: yarn run eslint .
- run:
    name: check formatting using prettier
    command: yarn run prettier --check .