github.com/cs3org/reva/v2@v2.27.7/CONTRIBUTING.md (about)

     1  Contributing
     2  ================
     3  
     4  First of all, thank you for your contribution!
     5  
     6  There are several areas where you can help, the [OpenSource Guide](https://opensource.guide/how-to-contribute/)
     7  is a nice guide emphasizing that not all contributions need to be code. 
     8  
     9  We also have a [Code of Conduct](https://github.com/cs3org/.github/tree/master/CODE_OF_CONDUCT.md)
    10  that is worth reading!
    11  
    12  Please **[open an issue first](https://github.com/cs3org/reva/issues/new)** for any bug report or new feature if there isn't
    13  already one opened. We use GitHub issues to keep track of failures in the
    14  software and addition of new features. A GitHub issue is a nice place to discuss ideas
    15  and get feedback from other members of the project.
    16  
    17  If you have general questions or you want guidance on how to start contributing
    18  you can reach us on [Gitter](https://gitter.im/cs3org/REVA).
    19  
    20  If you want to find an area that currently needs improving have a look at the
    21  open issues listed at the [issues page](https://github.com/cs3org/reva/issues). 
    22  
    23  For newcomers, issues with minor complexity are tagged 
    24  as [junior jobs](https://github.com/cs3org/reva/labels/junior-job).
    25  
    26  
    27  Reporting Bugs
    28  ==============
    29  
    30  If you've found a bug thanks for letting us know!
    31  It is a good idea to describe in detail how to reproduce 
    32  the bug (when you know how), what environment the bug appeared and so on.
    33  Please tell us at least the following things:
    34  
    35   * What's the version of binary you used? Please include the output of
    36     `revad --version` or `reva version` in your bug report.
    37   * What commands did you execute to get to where the bug occurred?
    38   * What did you expect?
    39   * What happened instead?
    40   * Do you know how to reproduce the bug?
    41  
    42  As more information you provide, the earlier we'll correct it!.
    43  
    44  Development Environment
    45  =======================
    46  
    47  The repository contains several sets of directories with code: `cmd/` and
    48  `pkg/` contain the main source code files.
    49  
    50  The dependencies of REVA are kept in the `go.mod` file in the root of the repository.
    51  In general we don't like to add new dependencies to the project and we try to stick as much
    52  as possible to the standard Go library. In cases this is not convenient, we accept only 
    53  external libraries that have a permissive license.
    54  
    55  
    56  To compile the REVA daemon and the REVA command line you can:
    57  
    58  ```
    59  $ git clone https://github.com/cs3org/reva
    60  $ make
    61  $ ./cmd/revad/revad --version
    62  version=v0.0.0 commit=639f48d branch=review go_version=go1.11.5 build_date=2019-04-17T13:57:17+0200 build_platform=linux/amd64
    63  ```
    64  
    65  If you only want to run the tests you can:
    66  
    67  ```
    68  $ make test
    69  ```
    70  
    71  Take a look at the Makefile in the root of the repository for all the available options.
    72  
    73  Providing Patches
    74  =================
    75  
    76  The workflow we're using is described on the
    77  [GitHub Flow](https://guides.github.com/introduction/flow/) website, it boils
    78  down to the following steps:
    79  
    80   0. If you want to work on something, please add a comment to the issue on
    81      GitHub. For a new feature, please add an issue before starting to work on
    82      it, so that duplicate work is prevented.
    83  
    84   1. First we would kindly ask you to fork our project on GitHub if you haven't
    85      done so already.
    86  
    87   2. Clone your repository locally and create a new branch.
    88      If you are working on the code itself, please set up the development environment
    89      as described in the previous section.
    90  
    91   3. Then commit your changes as fine grained as possible, as smaller patches,
    92      that handle one and only one issue are easier to discuss and merge.
    93  
    94   4. Push the new branch with your changes to your fork of the repository.
    95  
    96   5. Create a pull request by visiting the GitHub website, it will guide you
    97      through the process.
    98  
    99   6. You will receive comments on your code and the feature or bug that they
   100      address. Maybe you need to rework some minor things, in this case push new
   101      commits to the branch you created for the pull request (or amend the
   102      existing commit, use common sense to decide which is better), they will be
   103      automatically added to the pull request.
   104  
   105   7. If your pull request changes anything that users should be aware of (a
   106      bugfix, a new feature, ...) please add an entry to the file
   107      [CHANGELOG.md](CHANGELOG.md). It will be used in the announcement of the
   108      next stable release. While writing, ask yourself: If I were the user, what
   109      would I need to be aware of with this change.
   110  
   111   8. Once your code looks good and passes all the tests, we'll merge it. Thanks
   112      a lot for your contribution!
   113  
   114  Please provide the patches for each bug or feature in a separate branch and
   115  open up a pull request for each.
   116  
   117  We enforce the Go style guide. You can run `make lint` to fix formatting
   118  and discover issues related with code style.
   119  
   120  Every time you create a pull request, we'll run differents tests on Travis.
   121  We won't merge any code that doesn't pass the tests. If you need help to make the test
   122  pass don't hesitate to call for help! Having a PR with failing tests is nothing
   123  to be ashamed of, in the other hand, that happens regularly for all of us.
   124  
   125  Git Commits
   126  -----------
   127  
   128  It would be good if you could follow the same general style regarding Git
   129  commits as the rest of the project, this makes reviewing code, browsing the
   130  history and triaging bugs much easier.
   131  
   132  Git commit messages have a very terse summary in the first line of the commit
   133  message, followed by an empty line, followed by a more verbose description or a
   134  List of changed things. For examples, please refer to the excellent [How to
   135  Write a Git Commit Message](https://chris.beams.io/posts/git-commit/).
   136  
   137  If you change/add multiple different things that aren't related at all, try to
   138  make several smaller commits. This is much easier to review. Using `git add -p`
   139  allows staging and committing only some changes.
   140  
   141  
   142  For example, if your work is done on the reva daemon, prefix the commit
   143  message with `revad: my message`, if you work on the cli prefix it with `reva: my message`,
   144  if you work only on the package directory, prefix it with `pkg/pkgname: my message` and so on.
   145  
   146  Code Review
   147  ===========
   148  
   149  We encourage actively reviewing the code so it's common practice 
   150  to receive comments on provided patches.
   151  
   152  If you are reviewing other contributor's code please consider the following
   153  when reviewing:
   154  
   155  * Be nice. Please make the review comment as constructive as possible so all
   156    participants will learn something from your review.
   157  
   158  As a contributor you might be asked to rewrite portions of your code to make it
   159  fit better into the upstream sources.