Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
392 lines (333 loc) · 9.37 KB

CONTRIBUTING.md

File metadata and controls

392 lines (333 loc) · 9.37 KB
Raw

Agency Logo

Agency Contributing Guidelines

A code of conduct is a set of rules outlining the norms, rules, and responsibilities of, and or proper practices for, an individual. This applies to all people contributing to this repository in any form.

Table of contents

Commits

  • All commits must be verified. Learn how to sign commits using GitKraken.
  • All commit summaries must start with an uppercase letter.
  • All commit summaries must be written in present tense.
  • The commit summary and description are mandatory.
  • All commit descriptions must be written in past tense.
  • The commit headline must have a maximum of 71 chars.
  • The commit message must have a maximum of 71 chars per line.
  • If possible, include link to online topic as reference Ref: .
  • The purpose of the commit and your intentions behind it must be clear.
  • Include references to issues if applicable.
  • No commit, under no circumstances, should be pushed to master directly.
  • Each commit should only serve one distinct purpose.

Pull Requests

  • Each pull request should only follow one general topic.
  • You must follow the template for creating a pull request.
  • Each pull request must have at least one assigned developer.
  • Each pull request must have a label. If issues are present, it has to include those at a minimum.
  • Each pull request should be merged by a reviewer.
  • Each pull request has to pass all checks and reviews before merging.
  • Each pull request should include linked issues. Although it is not mandatory, it helps to track the thoughts of the developers and is therefore strongly advised.

Coding Style

We generally follow the ESLint ES6 rules. This code of conduct will outline some of the most important rules and showcase some of the use-cases.

It is recommended to use Visual Studio Code with all recommended Extensions when working on code with the agency or under the agency’s supervision. Use the built-in code quality improvement tool Prettier as often as possible. It does not only help you to keep focus and be more efficient, it also improves the code quality tremendously

The following rules are one of the most important.

  • Try to keep the maximum line length below 80. The maximum line length is 120.

Bad

let foo = { "bar": "This is a bar.", "baz": { "qux": "This is a qux" }, "difficult": "to read" };

Good

let foo = {
 "bar": "This is a bar.",
 "baz": { "qux": "This is a qux" },
 "easier": "to read",
};
  • Use double quotes instead of single quotes

Bad

let test = 'test';

Good

let test = "test";
  • These are the allowed comments standards:
/**
 * This is a multiline header comment.
 */
 
/**
 * This is a multiline header comment.
 * It has multiple sentences.
 */
 
 /*
  * This is a multiline comment
  */
 
 /*
  * This is a multiline comment.
  * It has multiple sentences.
  */
 
//> This is a header and can introduce following, related comments

/* This is a single line comment preffered to use in Typescript */

// This is a single line comment preffered to use in Javascript

// This is a single line comment preffered to use in Javascript. 
// It has multiple sentences.

/**
 * This is a multiline header comment which contains single line JSDoc tags.
 * @description And that's why you should never add dots here
 * @description Or here
 */
 
 /**
  * This is a multiline header comment which contains multiline JSDoc tags.
  * @description And that's why you should 
  *              add dots here.
  * @description Or
  *              here.
  */
  • Use regions if you have more than 3 distinct areas in your file.
  • (Such as imports, classes, functions, exports, …). This helps to organize the file.
//#region > Classes
/**
 * @class Short class description
 * @description Longer class description
 */
class Foo {
  constructor()
}
//#endregion

  • These are the default regions to use for organizing:

    • Imports
    • Interfaces
    • Classes
    • Functions
    • Exports

  • Custom regions can also be definied if none of the above regions fits for the case.

  • Anchors can be used to easily find code snippets inside the code

//#PACKAGE snek-client
//## npm install snek-client

  • The default anchors are:

    • #PACKAGE
    • #DEBUG
    • #ENTRYPOINT
    • #ERROR

  • A class should be structued using static, abstract fields & methods

//> Static Fields
//> Abstract Fields
//> Fields

//> Static Methods
//> Abstract Methods
//> Methods
  • Fields:
//> Fields
/**
 * @description Necessary for status
 */
boolean: status;
  • Abstract Fields:
//> Abstract Fields
/**
 * @description Necessary for database processing.
 */
abstract id: number;
  • Static Fields:
//> Static Fields
/**
 * @static
 * @description Provides access to the SOAssembler to provide functionality
 *              like create, all, filter,...
 *
 * @tutorial Usage: "public static objects =
 *                   StatementObject.getObjects(osmModel);"
 */
static objects: SOAssembler;
  • Methods:
//> Methods
/**
 * Render object.
 *
 * @param filter List of keys to filter by.
 * @returns {any} The filtered object.
 * @description Filter the object by a list of keys.
 */
render(filter: string[]): any {
  return helper.general.squeezer(this, filter);
}
  • Abstract Methods:
//> Abstract Methods
/**
 * @abstract
 * @returns {Boolean} A check if the database write process was successful.
 * @description Writes the statement object to the database.
 */
abstract save(): void;
  • Static Methods:
//> Static Methods
/**
 * @static
 * @param self A implementation of a statement object.
 * @returns {SOAssembler} A SOAssembler object.
 * @description Generate a new SOAssembler object, with the provided osm
 *              model.
 */
static getObjects(self: any) {
  return new SOAssembler(self);
}
  • Get and Set should also by commented using this style:
//> Getter
get pointer(): number {
  return this._pointer;
}

//> Setter
set pointer(values: number) {
  if(this.repositories.length >= value + 1){
    this._pointer += 1;
  } else {
    console.error(`
Pointer cannot be increased. The maximum has already been reached.
`);
  }
}
  • Try to keep the line count in one single file below 400.
  • After declaring variables, add a new line.
const a = 1;
const b = 2;

return a + b === 3 ? true : false;
  • The indentation must be 2 spaces.
  • Use const and let where ever possible. Do not use var if not required.
  • Variable should be named in camel case.

Bad

let my_test = "test";

Good

let myTest = "test";
  • There should be a newline after calling the super() function.
constructor(args: ITest) {
  super();

  this.test = "test";
}
  • There should be a newline after initializing the variables.
createTest(fields: any): Test {
  let test = Test.objects.create(fields);
  
  return test;
}
  • There should be a newline after an if statement.
checkTest(fields: any): Boolean {
  if (fields === null) {
    return false;
  }
  
  return true;
}
  • There should be a newline after a multiple line variable declaration

Bad

const testA = {
  a: "",
  b: "",
}
const testB = {
  b: "",
  a: "",
};
const a = "a";
const b = "b";

Good

const testA = {
  a: "",
  b: "",
}

const testB = {
  b: "",
  a: "",
};

const a = "a";
const b = "b";
  • Create a new line if the code is logically seperated. Bad
let a = 81;
let b = 1701;

a = a + 5;
a = 2 / 1;
a = a % 10;
b = b - 2000;
b = b * 1.5;
console.log();
console.log();

Good

let a = 81;
let b = 1701;

a = a + 5;
a = 2 / 1;
a = a % 10;

b = b - 2000;
b = b * 1.5;

console.log();
console.log();
  • Local imports should be placed below external imports.
import moment from "moment";

import * from "./test";

Versioning

  • Each merge of a branch to master should have a suitable change in the version if applicable.
  • Each change in version has to be documented with the creation of a new release, including a changelog.
  • Always use semantic versioning. (Major, Minor, Patch) See https://semver.org/ for more information.

Creators

This coding style and GitHub guidelines is a product of years of coding experience within the team of the Agency, including Christian Aichner @Aichnerc and Florian Kleber @kleberbaum.

Notable contributors to our coding style: Nico Schett @schettn, David Pinterics @pinterid

SPDX-License-Identifier: (EUPL-1.2) Copyright © 2020 Werbeagentur Christian Aichner