Here is a proposal for the Court Policy and the primary document for Feature:
Xdai JS Development Court Policy
Feature - Primary Document
Court Policy
Court Purpose
This court serves to arbitrate development disputes. This can include:
- Verifying that code proposal complies with the specifications
- Verifying that code proposal complies with the good development practices
- Verifying that developer followed the development workflow
Example
- A dispute about whether a code is buggy or not when running.
Feature - Primary Document
This document details the acceptance criteria of claims submitted to challenge the source code provided by a developer to complete a task.
This policy serves one main purpose:
Ensuring claims who prove that the developer did not follow good development practices or the specifications described by the client.
The jurors are expected to refer to the specificities of each individual cover policy which can be detailed in a README.md, CONTRIBUTING.md, POLICY.md or a specific document included in the specifications. This document is valid only if it was edited before the job was created. In the case of widely used versioning software such as Github, Gitlab or Bitbucket, the date of issue is sufficient evidence to timestamp the document.
In case of any discrepancy between a specific cover policy and this general claims acceptance policy, the specific policy should be considered as the source of truth.
Challenge Claim Acceptance Criteria
The grounds on which a challenge claim is valid are:
- non-compliance with specifications
- non-compliance with good development practices
- non-compliance with development workflow
Compliance with specifications
First of all, the specifications must be detailed enough for us to know whether the developer has completed the task or not. If they are not, the jurors are invited to refuse to vote.
The developer shall provide, if not previously described, the means to functionally test the code.
The first developer to claim the reward and meet the specifications is entitled to receive the award. All subsequent code proposals, even those that improve the code proposal, are entitled to be challenged since it is the first proposal who met the specifications that must be accepted.
Compliance with good development practices
In general, the developer must comply with the implicit rules described by the source code as long as it is consistent and respects recognised conventions and standards.
Failure to comply with one or more of these rules is not enough to make a challenge claim. At the very least, more than 5% of the code should not respect these good practices.
Code style
Ideally, a linter will explicitly describe the rules of the style code as an Eslint or JSCS file for example.
If a formatter has been set up, such as Prettier for example, it will be the responsibility of the developer to run it to format the code within the defined rules.
Indentation
Indentation is usually 2 spaces for javascript but sometimes it can be 4 spaces or a tab. The important thing is that it is consistent and respects the indentation of the blocks.
Statement Rules
For readability, avoid lines longer than 80 characters.
The use of a semicolon to close a statement is optional, depending on the project. The important thing is that this rule is consistent throughout the code.
Spaces
Always put spaces around operators ( = + - * / ), and after commas.
Use one space before the opening bracket.
Naming conventions
Variable names
Identifier names (variables and functions) must use the camelCase naming convention exception made to global constants in UPPERCASE.
Preference should be given to explicit variable names that describe their purpose, avoiding acronyms, generic names and abbreviations that sometimes cause confusion.
File names
Files names must use the naming convention kebab-case or camelCase exception made to component files sometimes in PascalCase or special files like README.md.
Comments
Code comments are not required unless there is complex code that needs to be explained so that it does not take too long to understand.
Architecture
Project structure
Several designs are possible like folders-by-feature, atomic or specific to a framework, the important thing is to have a coherent and consistent structure.
Service architecture
The choice of tools and their orchestration must be made according to the need, for example it would be a mistake to opt for a relational database in a Big Data project with a significant need for data storage.
The architecture must be simple and avoid being overloaded by non-essential services to meet the specificities.
Optimisation and performance
Seeking to optimize performance does not mean that this optimization is detrimental to the readability and maintenance of the code unless it is specified in the specifications that seeking performance is essential.
The ideal is to try to make simple code and avoid any form of over-engineering.
Tests
Writing tests for new features is not necessary unless explicitly requested in the specifications.
They should at least cover passing cases if they are required.
Third software
Avoid unnecessarily adding packages for pieces of code that can simply be written or retrieved so as not to affect the performance, the maintenance and the security of the application.
Compliance with development workflow
Here is the basic workflow for contributing:
- Fork the project
- Create a branch and work on it
- Publish the branch on its fork
- Create the pull-request
It will also be necessary if possible to have a clear Git history with short and well named commits (see conventional commits).
You can also comment directly on the google document: https://docs.google.com/document/d/14qWb4sQpvA-NPJEnqHIJu8LmrJeMt7uynt9JqQz2qGg/edit#
