PAiP Web Developer Guide

Git Workflow

So someone one time long ago though about Git as good tool and found good solution for naming branches and complete workflow. It’s called GitFlow. People liked that and made own ways of this workflow to fit them better. That’s start of our workflow.

I will write about our flow only. If you will want to learn about GitFlow go to section FF maybe you will find something useful for you there.

PAiP Web GitFlow

Base Branches

So everything starts from 2 base branches:

master - Holding your current stable state of Project
develop - Holding your current development state of Project

Note:
If you are administrator of Project then these 2 branches you want to make as protected branches.

Master branch should hold history of releases.
Develop branch should hold history of development of releases.

Feature Branches

So now you would want to make some new feature.

Make new feature branch of develop
Make your new awesome features
Make your PR or just merge your branch to develop
After your all work on features make stable release so change Changelog ,merge to master or PR and merge to master afterwards add tag

Ok so that’s the workflow with features let’s destruct it into smaller and easier to understand parts.

Make feature branch of develop
Feature branches have this naming scheme based on your project needs. If you don’t know what naming convention project uses just ask in Issue.
Naming Conventions for Feature Branches:
- feature/<name-of-feature>
- feature/<source-like-trello>/<name-of-feature>
- feature/<source-like-trello>/<identifier-of-task>
- feature/<source-like-trello>/<identifier-of-task>/<name-of-feature>
- feat/<name-of-feature>
- feat/<source-like-trello>/<name-of-feature>
- feat/<source-like-trello>/<identifier-of-task>
- feat/<source-like-trello>/<identifier-of-task>/<name-of-feature>
- issue-<number-of-issue-on-git-issue-board-like-github>
- issue/<number-of-issue-on-git-issue-board-like-github>
- issue-<number-of-issue-on-git-issue-board-like-github>/<name-of-feature>
Examples for PWBS Project in time of writing:
- issue-x/gitlab-ci
- issue-7/command-runner-fixes
- feat/trello/Jfq3zI8z/38-docker-container
Just write your code. Just that what you want to change or make.
After your work make a PR from your branch to develop. If you are working alone on Project you may want to just merge your branch to develop manually. I don’t advice that but there is possibility if you really would need to.
After some features, fixes and all other work make stable release.

change Changelog about Changelogs we will talk about in section 4, for now just know that it exists and it is needed to be changed on release.
After that make PR (same thing what to 2 applies everywhere) from develop to master
After merge of this PR add tag to repository with version as name. (for example v.0.1.0 or just 0.1.0).

Release Branches

In some cases you need to use release branches to support and bugfix some versions of your project.
If you are working on something big you might just work on special branch for version you are build. Made from develop branch like v.<version>.x (for example v.0.6.x).
But if you want to maintain your older versions or just make them as branches for documentation.
Then name your release branches in one of these ways:

release/<release-version>
version/<release-version>

This ways is not adviced but sometimes it can be the best for temporary release branch for example:

v.<release-version>
<release-version>

HotFix Branches

If you need to fix something on stable version for temporary fix while you are working on better fix in next stable release. You should use hotfix branch.

Hotfixes are handled this way:

Make a new hotfix branch based on master
Hotfix Branch Name Convention:
- hotfix/<name-of-issue-which-you-are-fixing>
- hotfix/<source-like-trello-or-github>/<identifier-of-task>
- hotfix/<source-like-trello-or-github>/<identifier-of-task>/<name-of-issue-which-you-are-fixing>
Fix what you need to fix
Change changelog, Make PR
Merge it, Release new version of Project, add tag on repository

Git Cheatsheet

Git

git init - Initialization of Local Repository
git add <File> - Add file to changes staged for commiting
git add -A - Add all changed files to changes stage for commiting
git commit -m "<message>" - Commit staged changes to your Local Repository
git remote - Managing Remote Repositories connected with current Local Repository
- git remote add <name> <repository-url> - Connect Remote Repository with current Local Repository
- git remote rm <name> - Disconnects Remote Repository with current Local Repository
- git remote show <name> - Shows information about Connection with Remote Repository
git push - Push Local Repository to Remote Repository
git push <remote> <branch> - Push Branch of Local Repository to Remote Repository
git push -u <remote> <branch> - Set Remote Repository Branch to default to this one on this branch and push Local Repository to Remote Repository
git pull - Pull Changes from Remote Repository to Local Repository
git checkout <file> - Restore specified file to state before current changes
git checkout <branch> - Restore state of current branch changes of specified branch
git tag <name> - Tags current changes (commit) with specified name

PR Workflow

So you want to make some functionality. Now how to do it properly?

We will skip parts of clean Git Workflow because it was covered in previous chapter. But we will reference to it.

So let’s say you want to make new powerful Watcher Mode for <abbr title=“PAiP Web Build System”>PWBS</abbr>. Now what you should do to start doing it properly?

Firstly make fork of repository if you haven’t done it. (People accepted to PAiP Web Open Team or PAiP Web Core Team may skip it because they might be able to work on original repository if they ask for it)
After that clone repository to some folder. (The best just clone development branch because there you will be working [git clone -b <development_branch> <repository_url>]).
When you have done it make new feature branch in way specified in previous chapter.
Make your awesome Watcher Mode functionality.

So you done your functionality? Ok let’s slowly get into this chapter real topic.

Firstly push all your changes to your branch. (For sure commit from time to time the best is to commit every working part of functionality)
Now make PR from your branch back to development branch.
In Title one short sentence what functionality you have done. In Description write more in details what you have done and if you had problem with something then with what and how next time we would have helped you.
On GitLab if you want you can add how much time you spent on this task (with all elements where you was stuck and etc.) simply by putting /est <time> in comment.
Ok, so you made your PR. For sure if project have CHANGELOG and things in that kind of thing make sure you added what you have done to it.
Next what you need to do is wait or just ask for Code Review of PR. In PAiP Web for that part are PAiP Web Admins which have to approve PRs.
After Code Review if there was need for fixes then fix elements specified and move back to waiting or asking for next Code Review. If your code went through Code Review fine then it will be merged.

Versioning

PAiP Web Semantic Versioning 1.0.0

Format of Version

Here are some options which you can use:

`${major}`
			`${major}.${minor}`
			`${major}.${minor}.${patch}`
			`${major}.${minor}.${patch}.${build}`
			`${major}.${minor}.${patch}+${metadata}
			`${major}.${minor}.${patch}-${release_type}${release_level}`
			`${major}.${minor}.${patch}-${release_type}${release_level}+${metadata}`

Meaning behind number names inside version

major
- Increment this version if you made one of the following:
  - Changed API so it is not backward compatible (API)
  - Changed UI in very strong manner (UI)
  - Changed meaning of any section which provide you with completely another meaning in the end (Text)
- Special versions that have specific meaning under this version:
  - 0.* - This is version for initial development. This version means that anything may change at any time and anything under this version shouldn’t be considered stable.
  - 1.0 - This is first release version. This version means that base of thing which you are building is considered stable enough that can be run or used on production environment.
minor
- This version have to reset to 0 on change of major
- Increment this version if you made one of the following (M1):
  - Changed API in backwards compatible manner (API)
    - New backward compatible functionality
    - New deprecation of functionality
    - New functionality or improvements are introduced within the private code
  - Changed UI in any way that is not bug fix (UI)
  - Changed phrasing of any section which provide you with exactly same or similiar meaning in the end (Text)
patch
- Increment this version if you made one of the following (M1):
  - Changed API due to bug fixing in backwards compatible manner (API)
  - Changed UI due to bug fixing (UI)
  - Fixed typos or small phrasing issues which doesn’t change meaning (Text)
- Definitions needed for this version:
  - Bug fix - internal change that fixes incorrect behaviour
- This version have to reset to 0 on change of any upper level of version
build
- This element of version is used only in very specific situations
- It’s not recommended to use this if you don’t really need it
- Increment this version if you make new build of current version
- This version should to reset to 0 on change of any upper level of version
metadata
- Here is section where you can add your metadata if you need it
- It’s not recommended to use this if you don’t really need it
release_type
- This section of version is for specifing in which element of version lifecycle is current version
- Possible values of this section are:
  - dev
    - This specifies development version of application
    - Using this version should signalize to the user that this version is unstable and can have bugs because it’s still in active development
  - alpha or a
    - This specifies alpha version of application
    - Using this version should signalize to the user that this version is more stable than dev version but can have bugs because it’s still in active development.
    - In this version new features can go in.
  - beta or b
    - This specifies beta version of application
    - Using this version should signalize to the user that this version should be stable, still can have small bugs because of it’s development but features of it shouldn’t change.
  - rc or candidate
    - This specifies release candidate version of application
    - Using this version should signalize to the user that this version should be completely stable, this version should be mainly for getting feedback on new features and for finding last bugs that might be left.
release_level
- This part of version is for next number of version inside current version lifecycle
- Increment this version if you made any changes when inside a version lifecycle described above
- This version have to reset to 0 on change of any upper level of version or change of release type

Legend

M1 - These rules apply only for major > 0

Types of elements that can be versioned

API - If it is anything with public API interface
UI - If it is anything frontend related ( meaning everything which user can interact with as part of application )
Text - If it is anything text related ( meaning things like books, documentation etc. )

Rules of versioning

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

major, minor, patch, build and release_level are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0.
Once versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.

Precedence

'1' < '2'
			'1.1' < '1.2'
			'1.1.1' < '1.1.2'
			'1.1.1.1' < '1.1.1.2'
			'1.1.1+20130313144700' == '1.1.1+exp.sha.5114f85' // Metadata is ignored
			'1.1.1-dev1' < '1.1.1-dev2'
			'1.1.1-dev2' < '1.1.1-alpha1'
			'1.1.1-dev2' < '1.1.1-beta1'
			'1.1.1-dev2' < '1.1.1-rc1'
			'1.1.1-dev2' < '1.1.1-rtm1'
			'1.1.1-dev2+20130313144700' == '1.1.1-dev2+exp.sha.5114f85' // Metadata is ignored
			'1.2' < '1.2.1.2'
			'1.2' > '1.2-dev2'
			/*
			 * Precedense is on side of `1.4-dev1` but through package managers
			 * should be used `1.3` because `1.4-dev1` is pre release
			 */
			'1.3' < '1.4-dev1'

Changelog

PAiP Web Changelog Specification 1.0.0

What is a changelog ?

A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

Why make a changelog ?

To make it easier for users, contributors and everyone to see precisely what notable changes have been made betwwen each release (or version) of the project.

Who needs a changelog ?

People do. Whether consumers or developers, the end users of software are human beings who care about what’s in the software or anything else that need changelogs and versions. When it changes, people want to know why and how.

Release Block Sections

Special Sections

Informations - for specifing informations about specific release

Changes

Added - for new features
Changed - for changes in existing functionality
Deprecated - for soon-to-be removed features
Removed - for now removed features
Fixed - for any bug fixes
Security - for any fixes related to security vulnerabilities
Regression - for changes that are regressions

Rules of changelog

Changelogs are for humans, not machines
There should be an entry for every single version
The same types of changes should be grouped
Versions and sections should be linkable
The latest comes first
The release date of each version is displayed
Changes made in development of next release version should be under Unreleased Release Block
All dates in changelog should be ISO standard date (YYYY-MM-DD)

Filename of changelog

It should be one of the following:

CHANGELOG.md - Prefered

CHANGELOG.rst
HISTORY.md / HISTORY.rst

Yanked Release

Yanked releases are versions that had to be pulled because of a serious bug or security issue.
They should be noted in changelog as [YANKED] after version and date.

Example

# Changelog
				## [1.0.0] - 2017-06-20
				### Added
				- New feature A
				### Changed
				- Feature B to have additional power

Hello World

Information About Guide

Introduction

So what is this guide for ?

Why i created this guide ?

Dictionary

Git Workflow

Git Workflow

PAiP Web GitFlow

Base Branches

Feature Branches

Release Branches

HotFix Branches

Git Cheatsheet

Git

PR Workflow

Versioning

PAiP Web Semantic Versioning 1.0.0

Format of Version

Meaning behind number names inside version

Legend

Types of elements that can be versioned

Rules of versioning

Precedence

Changelog

PAiP Web Changelog Specification 1.0.0

What is a changelog ?

Why make a changelog ?

Who needs a changelog ?

Release Block Sections

Special Sections

Changes

Rules of changelog

Filename of changelog

Yanked Release

Example