ASWI - Pokročilé softwarové inženýrství » ASWI 2021 » Aplikace pro správu X.509 certifikátů (Yoso Czech s.r.o.) - JMSD

h1. Project guidelines

h2. Git

*Commits*

Commit message shall have the following format:

<pre>

Re #<id> - <short description> <details>

</pre>

* *id* issue ID from the Redmine

* *short description* brief description of the change

* *details* detailed list of changes (added classes, changed interfaces, ...)

Each commit shall have a reasonable size to make the reviews as simple as possible.

*Branches*

The name of the branch shall follow the following format:

<pre>

<id>_<description>

</pre>

* *id* RedMine issue ID

* *description* short description of the change based issue name - without special characters, words separated by underscores

# For each issue, a new branch shall be created.

# When the work on a branch is finished by the *issue owner*, the work is posted for a code review. 

# After that, the code can be merged to master by the *reviewer*. 

# After the merge, the *reviewer* is responsible for verifying software integrity. 

# _In case the integrity of the software is seriously broken, the task can be returned to the *issue owner*._

*Code review*

* Reviewer walks through the code and checks the coding convention, code readability, stability, etc...

* Reviewer is responsible for basic functionality testing

* Code review is tracked in GitLab via merge request

h2. RedMine

* Everyone can create an issue

* New issues must have the following fields filled in: Type, Title, Description, State = New

* Optionally one can set parent issue or watchers

* One has to update the spent time periodically

+Description:+ 

* Administrative: What has to be done, possible Wiki page references, what are the work products (where to store them - eg. in DMS), what shall the work products contain

* Functional: Description of the change, possible references to the requirement

h3. Issue life cycle

* When the issue is created it starts in the state @New@

* During iteration planning the issue effort is estimated with the team, iteration reference is set and the issue is set to state @Accepted@

* After effort planning is done for all issue, the issue is assigned to a team member and the issue moves to @Assigned@

* After the assignee finishes his work, the issue is moved to @Resolved@

* When work products are checked/reviewed, the issue is moved to @Verified@

* During retrospective the issues are evaluated and moved to @Closed@

h3. Issue types

* *Bug* - fix of software error found during testing or review

* *Enhancement* - Improvement (that is not specified in requirement specification) of an already implemented feature based on feedback from the customer or a team.

* *Feature* - Implementation of a new functionality based on requirement specification document, implementing functional tests

* *Task* - Any non-implementation/administrative task such as administrative or analysis.

h3. Issue category (relevant for @Feature@ only)

* *Implementation* - implementing new functionality, unittests

* *Testing* - implementing automated functional tests

h2. Code

h3. General

* Code and all comments shall be written in English

* Code review is done for all code changes

* Unit tests are done for all business logic parts 

* Python docstrings (bellow function header) shall be created for all functions describing the purpose, inputs and outputs

* Avoid using names that are too general or too wordy. Strike a good balance between the two

* When using CamelCase names, capitalize all letters of an abbreviation (e.g. HTTPServer)

h3. Packages

* Package names should be all lower case

* When multiple words are needed, an underscore should separate them

* It is usually preferable to stick to 1-word names

h3. Modules

* Module names should be all lower case

* When multiple words are needed, an underscore should separate them

* It is usually preferable to stick to 1 word names

h3. Classes

* Class names should follow the UpperCaseCamelCase convention

* Exception classes should end in “Error”

h3. Global Variables

* Global variables should be all lowercase

* Words in a global variable name should be separated by an underscore

h3. Instance Variables

* Instance variable names should be all lower case

* Words in an instance variable name should be separated by an underscore

* Non-public instance variables should begin with a double underscore

* If a protected attribute is necessary to be used, the variable name shall start with a single underscore

* If an instance name needs to be mangled (interpreter rewrites the name in order to avoid name conflicts in subclasses), two underscores may begin its name

h3. Methods

* Method names should be all lower case

* Words in a method name should be separated by an underscore

* Non-public method should begin with a single underscore

* If a method name needs to be mangled, two underscores may begin its name

h3. Method Arguments

* Instance methods should have their first argument named ‘self’.

* Class methods should have their first argument named ‘cls’

h3. Functions

* Function names should be all lower case

* Words in a function name should be separated by an underscore

h3. Constants

* Constant names must be fully capitalized

* Words in a constant name should be separated by an underscore

h2. Design

This section describes guidelines of how to treat design changes in during issue implementation

# Evaluate if the change must be reflected in the design - helper object doesn't have to be specified in the design, only the most important classes and services must be described down to a level of the public interface.

# If a change must be done, take a mutex in @Design Mutex@ channel in MS Teams

# Do the necessary change and do a commit immediately

# Free the taken mutex in @Design Mutex@ channel in MS Teams. Append a short change message while freeing the mutex.