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).

* Each method that raises an Exception shall declare the exception in the docstring. This declaration shall be propagated up through the call graph.

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 during issue implementation.

The design changes are always done on the branch: 

<pre>

design_update_iteration_<iteration #>

</pre>

# 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.