ASWI - Pokročilé softwarové inženýrství » ASWI 2021 » OpenData vlastní téma (KIV) - Tři Mušketýři

h1. Conventions and Guidelines (WIP)

h2. Issue Management

h3. Creating/Editing an Issue

h4. Status

* *New*

Use this status, when you're creating an issue and you don't know, which team member should resolve it, or if the issue concerns the whole team (e.g. team meetings)

* *Accepted*

Use this status, when the issue is for a doing work on a task, which was not originally requested by the sponsor???

* *Assigned*

Use this status when there is a known assignee for the issue. In such a case, fill in the assignee as well.

* *Resolved*

Use this status, when you finished working on the issue.

* *Invalid*

Use this status, when the issue is not going to be worked on.

h4. Priority

Available priority levels are:

* *Low*

* *Normal*

* *High*

* *Urgent*

Setting a priority other than *Normal* is especially important, when dealing with issues in back log. That is, if an issue was not resolved in a past iteration and the issue needs to be finished as soon as possible, assign *High* or *Urgent* priority to it. If resolving the issue can wait, use *Low* priority. 

Also, when an issue is due a date before the end of the iteration, because some other isues depend on it, it should have *High* or *Urgent* priority as well.

h4. Tracker

This section explains, which tracker should be used for which type of issue.

* *Bug*

Use this tracker when the issue references a known bug that needs to be fixed.

* *Enhancement*

???

* *Task*

Use this tracker for issues related to implementation of a designed/analyzed part of the system.

* *Support*

Use this tracker for issues related to non-implementation task, e.g. any meeting issues, wiki editing, ...

* *Feature*

???

h3. Logging Time

When logging time for an issue, you should write a short comment, unless the subject of the issue is self-explanatory and the issue is going to be resolved, after you log the time, e.g. logging time for meetings.

h4. Activity for Time Logging

* *Unspecified*

Do not use this activity.

* *Analysis*

Use this activity, when you're logging time for anything analytical, for example research/brainstorming of any kind/...

* *Design*

Use this activity, when you're logging time for designing something, however *Analysis* can be used instead.

* *Implementation*

Use this activity, when you're logging time for implementing (coding) anything.

* *Verification*

Use this activity, when you're logging time for verifying someone else's work.

* *Documentation*

Use this activity, when you're logging time for creating/editing some documentation for exaplmple in some wiki page(s).

* *Administrative*

Use this activity for meetings.

If the work you did matches more than one of the activities, either log time separately or choose such activity you spent most time doing.

h2. Code Contributions (Commits)

h3. Linking Commits to Issues

Every commit must be linked to an issue, i.e. in each commit use the key word *Re #<issue-no>*. Alternatively, you can use the key word *refs #<issue1-no>, #<issue2-no>*, although it is preferable for each commit to be linked with exaclty one issue.

If you think your commit is not related to any existing issue, link it to the "Refactoring" issue (such issue will be prepared for every iteration).

It is preferable for the keyword(s) to appear at the very beginning of a commit message.

You can use other keywords for referencing issues in commit messages, e.g. *closes, fixes, done, fixed* - these keywords also affect the issue itself. It is not required to use these keywords.

Note.: The keywords are caseinsensitive and at least one blankspace or colon is needed between the keyword and the first hash to produce a match (taken from Redmine doc).

h3. Commit messages

Every commit must have a commit message briefly explaining what the changes in the commit do.

h3. End of Iteration Tags

At the end of every iteration, the team members' work in separate branches should be merged into the master branch. This merge commit should be tagged as the end of iteration.

h2. Coding and Code Documentation

When coding, use the generally known best practices (whether they concern the used language or not), see some of the coding conventions for C# at https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/coding-conventions.

h3. General Naming Conventions

https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/general-naming-conventions

Choose easily readable identifier names

Favor readability over brevity

Do not use underscores, hyphens, or any other nonalphanumeric characters

h3. Capitalization Conventions

https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/capitalization-conventions

Use PascalCasing (i.e. camelCasing with the first character capitalized) for naming the following types of identifiers:

* Namespace

* Type

* Interface

* Method

* Property

* Event

* Field

* Enum value

Use camelCasing for parameters.

Use ALL_CAPS for constants.

h3. Code Commenting

Use documentation comments for classes and methods (see https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/documentation-comments)

Use in-code comments too - the rules for this aren't strict, but try to comment every line/block of code, which might be even a little unclear to the reader

Sign each file you create (at the beginning of the file add a comment with the following line): "Author: Your Name"

h2. Wiki Documentation

On the wiki main page, you can find links to most of the important pages related to the project.

On some of the pages, the links to child pages appear in the text - if you struggle to find anything, go to *Index by title* and find the page you are looking for there.

Write/edit pages in English.