diff --git a/.arcconfig b/.arcconfig new file mode 100644 --- /dev/null +++ b/.arcconfig @@ -0,0 +1,3 @@ +{ + "phabricator.uri": "https://git.kolab.org" +} diff --git a/docs/development_standards b/docs/development_standards new file mode 100644 --- /dev/null +++ b/docs/development_standards @@ -0,0 +1,114 @@ += Development Standards for the PACK Project + +This document describes the standard processes and practices used in the +development of this project. All participation must be done in the spirit +of these guidelines. + +Above all else, the goal is clear, elegant, high-performance code written, +tested and maintained collaboratively in an open and inviting environment. + +== Technology + +PACK is written with Elixir (http://elixir-lang.org/) and Phoenix Framework +(http://www.phoenixframework.org/), a language and web app framework designed +for high reliability and scalability. + +The SQL backend used for structured data is PostgreSQL. + +== Team Coordination + +Development roadmaps, sprints, defect reports, code review and more all happens +on http://git.kolab.org. This is our primary tool for day-to-day development +and the best place to follow and participate in the project. + +Discussion between developers, designers, and users occurs on devel@kolab.org, +the Kolab Community Hub web forums, and the #kolab irc channel on +irc.freenode.net. + +We work in weekly sprints where we tackle tasks recorded on git.kolab.org. See +development workflow below. + +== Tools and Practices + +=== Coding Style + +This project follows the Elixir community style guide: + + http://elixir.community/styleguide + +Rule of thumb: write code that looks like the code that already exists in +the repository! + +=== Development Workflow + +The basic workflow can be described as: + + * create a task on git.kolab.org + * create a corresponding branch in git + * write tests and application code + * create a review request when ready + * iterate until consensus is the branch is ready for merging + * merge branch into main development branch (develop) + +All development should map to a task on git.kolab.org on the PACK project +workboards. This allows us to keep momentum and focus collectively as a team. +These tasks are priotized on the shared PACK workboard, from which we organize +weekly development sprints. + +The main PACK workboard contains the epics ahead of us, and their status. Each +actively developed epic has its own workboard as a sub-project, and these boards +are populated with individual tasks which are claimed by developers and scheduled +into sprints. + +Git Flow is used for daily development: + + https://github.com/nvie/gitflow + +In practice this means that all new development happens in feature branches +based on the develop branch. Features considered "ready" are merged into +develop, and periodically a release is made which results in develop being +merged into master. Bug fixes are also done in branches, with one branch +per fix, and these can be merged down into develop as well; if it must +be shipped immediately then it may be done in a hotfix branch (branched +from master) and trigger a new release. Thankfully, all of this branch +gymnastics is managed for us with the `git flow` tool. + + +=== Code Review + +All new development goes through code review prior to acceptance. We use +git.kolab.org for code review, and you can create/modify differentials using +the arc command line tool or the web interface. Reviews are made available +here: + + https://git.kolab.org/differential/ + +Tests are a must. While we are not obsessive about hitting 100% coverage, +we are obsessive about useful and complete testing. Of course, being written +in Elixir, we use ExUnit for testing. Also consider the use of property +based testing with ExCheck when and where appropriate. + +Credo is included as a dev dependency and used regularly to "lint" the +code base. Every contributor is encouraged to run `mix credo` from time to time +and take action on the issues it notes. + +=== tsung + +We use tsung for performance and load testing: + + http://tsung.erlang-projects.org/ + +Every public API should have a corresponding tsung workload defined, and +be classified into one of three categories of performance profiles: + + * high concurrency, quick response: 100k+ simultaneous users with minimal + wallclock time to response + * high concurrency: 100k+ simultaneous users, response time not important + * low concurrency: less than 1000 simultaneous users, measure for response + time and correctness + +== Release Schedule + +As this is an embryotic project, there is currently no release schedule. + +