path: root/CONTRIBUTING

############
Contributing
############

.. contents:: Table of Contents

We use `Github`_ for managing code and issues and `GerritHub`_ for reviews.

.. _GerritHub: https://review.gerrithub.io/admin/projects/SamsungSLAV/weles
.. _Github: https://github.com/SamsungSLAV/weles


*****************
How to contribute
*****************

Reporting bugs
==============

Create issue on `GitHub`_.

Suggesting enhancements
=======================

Create issue on `GitHub`_.

Code contributions
==================

Check issues on `Github`_.

***********
Styleguides
***********

Git
===

Commit message
--------------

Check following articles regarding commit messages:

- `Tim Pope's blog post`_
- `Chris Beams blog post`_

Each commit message must be signed-off. This means that the contributor agrees
to `Developer Certificate of Origin`_.

If committer will not be responsive but his patch will be chosen to be merged,
some fixes might be added by someone else. Signoff will show original author
even when someone else will commit it.

.. _`Tim Pope's blog post`: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
.. _`Chris Beams blog post`:  https://chris.beams.io/posts/git-commit
.. _`Developer Certificate of Origin`: https://developercertificate.org/


Commit size
-----------

Each feature should be on its designated branch. This allows to divide features
into small commits which are easier to review.

Branching schema
----------------

Main branches
^^^^^^^^^^^^^

Currently there is one main branch: ``master``.

Feature branches
^^^^^^^^^^^^^^^^

Feature branches should be named uniquely and identify the feature developed.

Merge strategy
^^^^^^^^^^^^^^

Feature branches are always merged without fast-forwarding to keep branch
information.

Release strategy
----------------

Releases are flagged on master branch using git tag. We use `Semantic
Versioning 2.0`_ .

.. _`Semantic Versioning 2.0`: https://semver.org/

Coding style
============

Automatic formatters
--------------------

We use both gofmt_ and goimports_. It is recommended to set your editor to run those two on save.
It is desired to place internal SLAV imports at the bottom.

.. _goimports: https://godoc.org/golang.org/x/tools/cmd/goimports

Line breaks
-----------

Breaking lines on 100 chars
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The goal of this rule is to have code easy to read on vertical monitor or two files on a horizontal
monitor.

We consider tab to be 4 chars.

Breaking function signature when parameter list goes over 100 chars
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block::

  // Having a function signature like this, where the paginator weles.ArtifactPagination parameter
  // exceeds the 100 chars:                                                                   here: v
  func (aDB *ArtifactDB) Filter(filter weles.ArtifactFilter, sorter weles.ArtifactSorter, paginator weles.ArtifactPagination) ([]weles.ArtifactInfo, weles.ListInfo, error) {
      results := []weles.ArtifactInfo{}
      ...
  }

  // You should change it to:
  func (aDB *ArtifactDB) Filter(f weles.ArtifactFilter, s weles.ArtifactSorter,
       p weles.ArtifactPagination) ([]weles.ArtifactInfo, weles.ListInfo, error) {

       results := []weles.ArtifactInfo{}
       ...
  }
  // Please remember to add new line between functon signature and body to indicate end of function
  // signature. This is because gofmt indents them to the same level.

Breaking function signature when return goes over 100 chars
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block::

  // Having a function signature like this, where *Downloader return parameter exceeds
  // 100 chars:                                                                               here: v
  func newDownloader(notification chan weles.ArtifactStatusChange, workers, queueSize int) *Downloader {
      return newDownloader(notification, workerCount, queueCap)
  }
  // You should change it to
  func NewDownloader(notification chan weles.ArtifactStatusChange, workerCount, queueCap int,
  ) *Downloader {
      return newDownloader(notification, workerCount, queueCap)
  }
  // Please note lack of new line between function signature and body. They have different
  // indentation level thus new line is not necessary.

Breaking a struct literal when it goes over 100 chars
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block::

  // Having a line like below:
  f := weles.JobFilter{CreatedAfter: strfmt.DateTime(magicDate), CreatedBefore: strfmt.DateTime{}}
  // You should change it to:
  f := weles.JobFilter{
      CreatedAfter:  strfmt.DateTime(magicDate),
      CreatedBefore: strfmt.DateTime{},
  } // Note the comma in previous line and the closing brace in new line.

Tests
-----

We use Ginkgo_ which is BDD-style Go testing framework with Gomega_ which is a
matcher library.

.. _Ginkgo: https://onsi.github.io/ginkgo/
.. _Gomega: https://github.com/onsi/gomega

Static Analysis
---------------

We use `gometalinter`_ to check the code. To use locally, please download .v2
version and execute it in Weles repository root (or pass .gometalinter.json
explicitly) Below table contains overview of the checkers used in Weles.
Automatically generated code is not subject to static analysis.

+---------------------------+-------------------------------------------------------------------------------+
| Linter                    | Description                                                                   |
+===========================+===============================================================================+
| deadcode_                 | Find unused code                                                              |
+---------------------------+-------------------------------------------------------------------------------+
| errcheck_                 | Check that error return values are used.                                      |
+---------------------------+-------------------------------------------------------------------------------+
| goconst_                  | Finds repeated strings that could be replaced by a constant.                  |
+---------------------------+-------------------------------------------------------------------------------+
| gocyclo_                  | Computes the cyclomatic complexity of functions.                              |
|                           |                                                                               |
|                           | Max cyclomatic complexity: 15                                                 |
+---------------------------+-------------------------------------------------------------------------------+
| gofmt_                    | Checks if the code is properly formatted and could not be further simplified. |
+---------------------------+-------------------------------------------------------------------------------+
| golint_                   | Google's (mostly stylistic) linter.                                           |
+---------------------------+-------------------------------------------------------------------------------+
| `gosec (previously gas)`_ | Inspects source code for security problems by scanning the Go AST.            |
+---------------------------+-------------------------------------------------------------------------------+
| gosimple_                 | Report simplifications in code.                                               |
+---------------------------+-------------------------------------------------------------------------------+
| ineffassign_              | Detect when assignments to existing variables are not used.                   |
+---------------------------+-------------------------------------------------------------------------------+
| interfacer_               | Suggest narrower interfaces that can be used.                                 |
+---------------------------+-------------------------------------------------------------------------------+
| lll_                      | Report long lines.                                                            |
|                           |                                                                               |
|                           | Max line length: 100. Tab width: 4.                                           |
+---------------------------+-------------------------------------------------------------------------------+
| maligned_                 | Detect structs that would take less memory if their fields were sorted.       |
+---------------------------+-------------------------------------------------------------------------------+
| megacheck_                | Run staticcheck_, gosimple_ and unused_, sharing work.                        |
+---------------------------+-------------------------------------------------------------------------------+
| staticcheck_              | Statically detect bugs, both obvious and subtle ones.                         |
+---------------------------+-------------------------------------------------------------------------------+
| structcheck_              | Find unused struct fields.                                                    |
+---------------------------+-------------------------------------------------------------------------------+
| unconvert_                | Detect redundant type conversions.                                            |
+---------------------------+-------------------------------------------------------------------------------+
| unparam_                  | Find unused function parameters.                                              |
+---------------------------+-------------------------------------------------------------------------------+
| unused_                   | Find `unused variables`_.                                                     |
+---------------------------+-------------------------------------------------------------------------------+
| varcheck_                 | Find unused global variables and constants.                                   |
+---------------------------+-------------------------------------------------------------------------------+
| vet_                      | Reports potential errors that otherwise compile.                              |
+---------------------------+-------------------------------------------------------------------------------+
| vetshadow_                | Reports variables that may have been unintentionally shadowed.                |
+---------------------------+-------------------------------------------------------------------------------+

.. _gometalinter: https://github.com/alecthomas/gometalinter>
.. _deadcode: https://github.com/tsenart/deadcode
.. _errcheck: https://github.com/kisielk/errcheck
.. _goconst: https://github.com/jgautheron/goconst
.. _gocyclo: https://github.com/alecthomas/gocyclo
.. _gofmt: https://golang.org/cmd/gofmt
.. _golint: https://github.com/golang/lint
.. _`gosec (previously gas)`: https://github.com/securego/gosec
.. _gosimple: https://github.com/dominikh/go-tools/tree/master/cmd/gosimple
.. _ineffassign: https://github.com/gordonklaus/ineffassign
.. _interfacer: https://github.com/mvdan/interfacer
.. _lll: https://github.com/walle/lll
.. _maligned: https://github.com/mdempsky/maligned
.. _megacheck: https://github.com/dominikh/go-tools/tree/master/cmd/megacheck
.. _staticcheck: https://github.com/dominikh/go-tools/tree/master/cmd/staticcheck
.. _structcheck: https://github.com/opennota/check
.. _unconvert: https://github.com/mdempsky/unconvert
.. _unparam: https://github.com/mvdan/unparam
.. _unused: https://github.com/dominikh/go-tools/tree/master/cmd/unused
.. _`unused variables`: https://github.com/dominikh/go-tools/tree/master/cmd/unused#what-counts-as-usedunused
.. _varcheck: https://github.com/opennota/check
.. _vet: https://golang.org/cmd/vet
.. _vetshadow: https://golang.org/cmd/vet/#hdr-Shadowed_variables

Documentation styleguide
========================

All documentation parts are gathered into Sphinx documentation.

User Documentation
------------------

For Sphinx documentation we follow `Benoit Bryon's styleguide`_.

Non Sphinx rst documents (such as README, CONTRIBUTING) follow only rules
listed below

* Whitespaces
* Line length (where possible)
* Headings

.. _`Benoit Bryon's styleguide`: https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html

API Documentation
-----------------

API Documentation is prepared according to `OpenAPI 2.0`_.

.. _`OpenAPI 2.0`: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md

Code Documentation
------------------

Currently Godoc is not used. It will be included in Sphinx documentation in
later stages of the project.