github.com/jaylevin/jenkins-library@v1.230.4/.github/CONTRIBUTING.md (about)

     1  # Guidance on How to Contribute
     2  
     3  **Table of Contents:**
     4  
     5  1. [Using the issue tracker](#using-the-issue-tracker)
     6  1. [Changing the code-base](#changing-the-code-base)
     7  1. [Jenkins credential handling](#jenkins-credential-handling)
     8  1. [Code Style](#code-style)
     9  1. [References](#references)
    10  
    11  There are two primary ways to help:
    12  
    13  * Using the issue tracker, and
    14  * Changing the code-base.
    15  
    16  ## Using the issue tracker
    17  
    18  Use the issue tracker to suggest feature requests, report bugs, and ask questions. This is also a great way to connect with the developers of the project as well as others who are interested in this solution.
    19  
    20  Use the issue tracker to find ways to contribute. Find a bug or a feature, mention in the issue that you will take on that effort, then follow the "Changing the code-base" guidance below.
    21  
    22  ## Changing the code-base
    23  
    24  Generally speaking, you should fork this repository, make changes in your own fork, and then submit a pull-request. All new code should have been thoroughly tested end-to-end in order to validate implemented features and the presence or lack of defects.
    25  
    26  ### Working with forks
    27  
    28  * [Configure this repository as a remote for your own fork](https://help.github.com/articles/configuring-a-remote-for-a-fork/), and
    29  * [Sync your fork with this repository](https://help.github.com/articles/syncing-a-fork/) before beginning to work on a new pull-request.
    30  
    31  ### Tests
    32  
    33  All pipeline library coding _must_ come with automated unit tests.
    34  
    35  Besides that, we have an integration test suite, which is not triggered during normal pull request builds. However, integration tests are mandatory before a change can be merged. It is the duty of a team member of the SAP/jenkins-library project to execute these tests.
    36  To trigger the integration test suite, the `HEAD` commit of the branch associated with the pull request must be pushed under the branch pattern `it/.*` (recommended naming convention: `it/<Number of the pull request>`). As a result, the status `integration-tests` is updated in the pull request.
    37  
    38  ### Documentation
    39  
    40  The contract of functionality exposed by a library functionality needs to be documented, so it can be properly used.
    41  Implementation of a functionality and its documentation shall happen within the same commit(s).
    42  
    43  ### Coding pattern
    44  
    45  Pipeline steps must not make use of return values. The pattern for sharing parameters between pipeline steps or between a pipeline step and a pipeline script is sharing values via the [`commonPipelineEnvironment`](../vars/commonPipelineEnvironment.groovy). Since there is no return value from a pipeline step the return value of a pipeline step is already `void` rather than `def`.
    46  
    47  #### EditorConfig
    48  
    49  To ensure a common file format, there is a `.editorConfig` file [in place](../.editorconfig). To respect this file, [check](http://editorconfig.org/#download) if your editor does support it natively or you need to download a plugin.
    50  
    51  ### Commit Message Style
    52  
    53  Write [meaningful commit messages](http://who-t.blogspot.de/2009/12/on-commit-messages.html) and [adhere to standard formatting](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
    54  
    55  Good commit messages speed up the review process and help to keep this project maintainable in the long term.
    56  
    57  ## Developer Certificate of Origin (DCO)
    58  
    59  Due to legal reasons, contributors will be asked to accept a DCO when they create their first pull request to this project. This happens in an automated fashion during the submission process. SAP uses [the standard DCO text of the Linux Foundation](https://developercertificate.org/).
    60  
    61  ## Jenkins credential handling
    62  
    63  References to Jenkins credentials should have meaningful names.
    64  
    65  We are using the following approach for naming Jenkins credentials:
    66  
    67  For username/password credentials:
    68  `<tool>CredentialsId` like e.g. `neoCredentialsId`
    69  
    70  For other cases we add further information to the name like:
    71  
    72  * `gitSshCredentialsId` for ssh credentials
    73  * `githubTokenCredentialsId`for token/string credentials
    74  * `gcpFileCredentialsId` for file credentials
    75  
    76  ## Code Style
    77  
    78  Generally, the code should follow any stylistic and architectural guidelines prescribed by the project. In the absence of guidelines, mimic the styles and patterns in the existing code-base.
    79  
    80  The intention of this section is to describe the code style for this project. As reference document, the [Groovy's style guide](http://groovy-lang.org/style-guide.html) was taken. For further reading about Groovy's syntax and examples, please refer to this guide.
    81  
    82  This project is intended to run in Jenkins [[2]](https://jenkins.io/doc/book/getting-started/) as part of a Jenkins Pipeline [[3]](https://jenkins.io/doc/book/pipeline/). It is composed by Jenkins Pipeline's syntax, Groovy's syntax and Java's syntax.
    83  
    84  Some Groovy's syntax is not yet supported by Jenkins. It is also the intention of this section to remark which Groovy's syntax is not yet supported by Jenkins.
    85  
    86  As Groovy supports 99% of Java’s syntax [[1]](http://groovy-lang.org/style-guide.html), many Java developers tend to write Groovy code using Java's syntax. Such a developer should also consider the following code style for this project.
    87  
    88  ### General remarks
    89  
    90  Variables, methods, types and so on shall have meaningful self describing names. Doing so makes understanding code easier and requires less commenting. It helps people who did not write the code to understand it better.
    91  
    92  Code shall contain comments to explain the intention of the code when it is unclear what the intention of the author was. In such cases, comments should describe the "why" and not the "what" (that is in the code already).
    93  
    94  ### Omit semicolons
    95  
    96  ### Use the return keyword
    97  
    98  In Groovy it is optional to use the _return_ keyword. Use explicitly the _return_ keyword for better readability.
    99  
   100  ### Use def
   101  
   102  When using _def_ in Groovy, the type is Object. Using _def_ simplifies the code, for example imports are not needed, and therefore the development is faster.
   103  
   104  ### Do not use a visibility modifier for public classes and methods
   105  
   106  By default, classes and methods are public, the use of the public modifier is not needed.
   107  
   108  ### Do not omit parentheses for Groovy methods
   109  
   110  In Groovy is possible to omit parentheses for top-level expressions, but [Jenkins Pipeline's syntax](https://jenkins.io/doc/book/pipeline/syntax/) use a block, specifically `pipeline { }` as top-level expression [[4]](https://jenkins.io/doc/book/pipeline/syntax/). Do not omit parenthesis for Groovy methods because Jenkins will interpret the method as a Pipeline Step. Conversely, do omit parenthesis for Jenkins Pipeline's Steps.
   111  
   112  ### Omit the .class suffix
   113  
   114  In Groovy, the .class suffix is not needed. Omit the .class suffix for simplicity and better readability.
   115  
   116  e.g. `new ExpectedException().expect(AbortException.class)`
   117  
   118  -->  `new ExpectedException().expect(AbortException)`
   119  
   120  ### Omit getters and setters
   121  
   122  When declaring a field without modifier inside a Groovy bean, the Groovy compiler generates a private field and a getter and setter.
   123  
   124  ### Do not initialize beans with named parameters
   125  
   126  Do not initialize beans with named parameters, because it is not supported by Jenkins:
   127  
   128  e.g. `Version javaVersion = new Version( major: 1, minor: 8)`
   129  
   130  Initialize beans using Java syntax:
   131  
   132  e.g. `Version javaVersion = new Version(1, 8)`
   133  
   134  Use named parameters for Jenkins Pipeline Steps:
   135  
   136  e.g. `sh returnStdout: true, script: command`
   137  
   138  ### Do not use _with()_ operator
   139  
   140  The _with_ operator is not yet supported by Jenkins, and it must not be used or encapsulated in a @NonCPS method.
   141  
   142  ### Use _==_ operator
   143  
   144  Use Groovy’s `==` instead of Java `equals()` to avoid NullPointerExceptions. To compare the references of objects, instead of `==`, you should use `a.is(b)` [[1]](http://groovy-lang.org/style-guide.html).
   145  
   146  ### Use GStrings
   147  
   148  In Groovy, single quotes create Java Strings, and double quotes can create Java Strings or GStrings, depending if there is or not interpolation of variables [[1]](http://groovy-lang.org/style-guide.html). Using GStrings variable and string concatenation is more simple.
   149  
   150  #### Do not use curly braces {} for variables or variable.property
   151  
   152  For variables, or variable.property, drop the curly braces:
   153  
   154  e.g. `echo "[INFO] ${name} version ${version.version} is installed."`
   155  
   156  -->  `echo "[INFO] $name version $version.version is installed."`
   157  
   158  #### Use 'single quotes' for Strings and constants
   159  
   160  #### Use "double quotes" for GStrings
   161  
   162  #### Use '''triple single quotes''' for multiline Strings
   163  
   164  #### Use """triple double quotes""" for multiline GStrings
   165  
   166  #### Use /slash/ for regular expressions
   167  
   168  This notation avoids to double escape backslashes, making easier working with regex.
   169  
   170  ### Use native syntax for data structures
   171  
   172  Use the native syntax for data structures provided by Groovy like lists, maps, regex, or ranges of values.
   173  
   174  ### Use aditional Groovy methods
   175  
   176  Use the additional methods provided by Groovy to manipulate String, Files, Streams, Collections, and other classes.
   177  For a complete description of all available methods, please read the GDK API [[5]](http://groovy-lang.org/groovy-dev-kit.html).
   178  
   179  ### Use Groovy's switch
   180  
   181  Groovy’s switch accepts any kind of type, thereby is more powerful. In this case, the use of _def_ instead of a type is necessary.
   182  
   183  ### Use alias for import
   184  
   185  In Groovy, it is possible to assign an alias to imported packages. Use alias for imported packages to avoid the use of fully-qualified names and increase readability.
   186  
   187  ### Use Groovy syntax to check objects
   188  
   189  In Groovy a null, void, equal to zero, or empty object evaluates to false, and if not, evaluates to true. Instead of writing null and size checks e.g. `if (name != null && name.length > 0) {}`, use just the object `if (name) {}`.
   190  
   191  ### Use _?._ operator
   192  
   193  Use the safe dereference operator  _?._, to simplify the code for accessing objects and object members safely. Using this operator, the Groovy compiler checks null objects and null object members, and returns _null_ if the object or the object member is null and never throws a NullPointerException.
   194  
   195  ### Use _?:_ operator
   196  
   197  Use Elvis operator _?:_ to simplify default value validations.
   198  
   199  ### Use _any_ keyword
   200  
   201  If the type of the exception thrown inside a try block is not important, catch any exception using the _any_ keyword.
   202  
   203  ### Use _assert_
   204  
   205  To check parameters, return values, and more, use the assert statement.
   206  
   207  ## References
   208  
   209  [1] Groovy's syntax: [http://groovy-lang.org/style-guide.html](http://groovy-lang.org/style-guide.html)
   210  
   211  [2] Jenkins: [https://jenkins.io/doc/book/getting-started/](https://jenkins.io/doc/book/getting-started/)
   212  
   213  [3] Jenkins Pipeline: [https://jenkins.io/doc/book/pipeline/](https://jenkins.io/doc/book/pipeline/)
   214  
   215  [4] Jenkins Pipeline's syntax: [https://jenkins.io/doc/book/pipeline/syntax/](https://jenkins.io/doc/book/pipeline/syntax/)
   216  
   217  [5] GDK: Groovy Development Kit: [http://groovy-lang.org/groovy-dev-kit.html](http://groovy-lang.org/groovy-dev-kit.html)