CONTRIBUTING.md

Git Flow

The project's overall git flow

1. The master branch contains production-ready code only, and is not allowed to push at by anyone except of maintainers and owners;
2. Each issue should be provided with a separate feature branch, called by a brief issue name (e.g. bootstrap-project); The branch should be created from the master one;
3. When a developer finishes, he/she creates a PR from the feature branch to master. Maintainers or admins review this PR, and eventually perform merging;
   1. When there are conflicts between feature branch and master, developer should resolve them by rebasing his feature branch on master (e.g. git rebase origin/master);
      1. Force pushing to the feature branch is allowed;
      2. Direct commits to master are not allowed;

Code style & formatting

The project uses a clojure formatter called cljstyle. This needs to be installed prior to work. To install, follow the below instructions. Generally, you should have cljstyle command available from your command line. You should also have the core.hooksPath git config set up (see above), as the pre-commit hook is used.

Workflow

Development

• To start development, create a deployment/local/.env file from the deployment/local/.env.template template and set environment variables from it.

• From the project root:

  # start local environment
  $ bb up
  
  # shutdown local environment
  $ bb down

• To develop in REPL, test and build, switch to the desired module directory: modules/backend or modules/frontend.

• From the module root:

  # run backend repl
  $ bb repl
  
  # check for outdated dependencies
  $ bb outdated
  
  # upgrade outdated dependencies
  $ bb outdated:upgrade

• In the backend REPL, run the following commands:

  • Run dev to load the development namespace:

    user=> (dev)
    #object[clojure.lang.Namespace ... "dev"]

  • In the dev namespace, run go to prep and initiate the system (requires a deployed local environment).
  • This creates a web server at http://localhost:8080:

    user=> (go)
    :initiated

  • In the dev namespace, when you make changes to the source code files, use reset to reload any modified files and reset the server:

    user=> (reset)
    :reloading (...)
    :resumed

Testing

• Integration tests require a deployed environment before run (bb up from the root of the project).

• From the module root:

   # run linters
   $ bb lint
  
   # run linters and fix issues
   $ bb lint:fix
  
   # run only unit tests
   $ bb test:unit
  
   # run only integration tests
   $ bb test:integration
  
   # run all tests
   $ bb test

Building backend

• From the module root:

  # run cleanup
  $ bb clean
  
  # run uberjar
  $ bb uber

Other tasks

• From the module/project root:

  $ bb tasks