zotregistry.io/zot@v1.4.4-0.20231124084042-02a8ed785457/CONTRIBUTING.md (about)

     1  # Getting Started
     2  
     3  ## Fork Repository
     4  
     5  [Fork](https://github.com/project-zot/zot) the zot repository on GitHub to your personal account.
     6  
     7  ```
     8  #Set golang environment
     9  export GOPATH=$HOME/go
    10  mkdir -p $GOPATH/src/github.com/project-zot
    11  
    12  #Get code
    13  go get github.com/project-zot/zot
    14  cd $GOPATH/src/github.com/project-zot/zot
    15  
    16  #Track repository under your personal account
    17  git config push.default nothing # Anything to avoid pushing to project-zot/zot by default
    18  git remote rename origin project-zot
    19  git remote add $USER git@github.com:$USER/zot.git
    20  git fetch $USER
    21  
    22  ```
    23  
    24  NOTES: Note that GOPATH can be any directory, the example above uses $HOME/go.
    25  Change $USER above to your own GitHub username.
    26  
    27  ## Build
    28  
    29  There are several ways to build the zot project. The resulting binaries are
    30  produced under bin/
    31  
    32  
    33  ## Using host's toolchain
    34  
    35  For fully-featured zot,
    36  
    37  ```
    38  make
    39  ```
    40  
    41  For a minimal dist-spec only zot,
    42  
    43  ```
    44  make binary-minimal
    45  ```
    46  
    47  For a zot that includes only the extensions that you specify,
    48  the available extensions that can be used at the moment are: sync, scrub, metrics, search.
    49  
    50  NOTES: When multiple extensions are used, they should be enlisted in the above presented order.
    51  
    52  ```
    53  make binary EXTENSIONS=a,b,c
    54  ```
    55  
    56  For a node exporter used by minimal dist-spec only zot,
    57  
    58  ```
    59  make exporter-minimal
    60  ```
    61  
    62  ## Using container builds (stacker)
    63  
    64  ```
    65  make oci-image
    66  ```
    67  
    68  ## Using container builds (docker)
    69  
    70  ```
    71  make docker-image
    72  ```
    73  
    74  # Project Structure
    75  
    76  ```
    77  .
    78  ...
    79  ├── cmd/zot             # Source code contains the main logic
    80  ├── cmd/zxp             # Source code contains the main logic for node exporter
    81  ├── docs                # Source code for Swagger docs
    82  ├── errors              # Source code for errors
    83  ├── examples            # Configuration examples to enable various features
    84  ├── pkg/api             # Source code contains the HTTP handlers
    85  ├── pkg/cli             # Source code that handles the commandline logic
    86  ├── pkg/compliance      # Source code that handles the dist-spec compliance logic
    87  ├── pkg/exporter        # Source code used by the node exporter
    88  ├── pkg/extensions      # Source code that handles the feature extensions
    89  ├── pkg/log             # Source code that handles logging
    90  ├── pkg/storage         # Source code that handles image storage
    91  
    92  ```
    93  
    94  ## Contribute Workflow
    95  
    96  PRs are always welcome, even if they only contain small fixes like typos or a few
    97  lines of code. If there will be a significant effort, please document it as an
    98  issue and get a discussion going before starting to work on it.
    99  
   100  Please submit a PR broken down into small changes bit by bit. A PR consisting of
   101  a lot features and code changes may be hard to review. It is recommended to
   102  submit PRs in an incremental fashion.
   103  
   104  Note: If you split your pull request to small changes, please make sure any of
   105  the changes goes to master will not break anything. Otherwise, it can not be
   106  merged until this feature complete.
   107  
   108  ## Develop, Build and Test
   109  
   110  Write code on the new branch in your fork. The coding style used in zot is
   111  suggested by the Golang community. See the [style doc](https://github.com/golang/go/wiki/CodeReviewComments) for details.
   112  
   113  Try to limit column width to 120 characters for both code and markdown documents
   114  such as this one.
   115  
   116  As we are enforcing standards set by
   117  [golangci-lint](https://github.com/golangci/golangci-lint), please always run a full 'make' on source
   118  code before committing your changes. This will trigger compilation, unit tests
   119  and linting. If it reports an issue, in general, the preferred action is to fix
   120  the code. We try to enforce the guideline that code coverage doesn't drop as
   121  code is added or modified.
   122  
   123  ## Automated Testing (via CI/CD)
   124  
   125  Once your pull request has been opened, zot will start a full CI pipeline
   126  against it that compiles, and runs unit tests and linters.
   127  
   128  ## Reporting issues
   129  
   130  It is a great way to contribute to zot by reporting an issue. Well-written
   131  and complete bug reports are always welcome! Please open an issue on Github and
   132  follow the template to fill in required information.
   133  
   134  Before opening any issue, please look up the existing issues to avoid submitting
   135  a duplication. If you find a match, you can "subscribe" to it to get notified on
   136  updates. If you have additional helpful information about the issue, please
   137  leave a comment.
   138  
   139  When reporting issues, always include:
   140  
   141  Build environment (golang compiler, etc)
   142  Configuration files of zot
   143  
   144  Log files as per configuration.
   145  
   146  Because the issues are open to the public, when submitting the log
   147  and configuration files, be sure to remove any sensitive
   148  information, e.g. user name, password, IP address, and company name.
   149  You can replace those parts with "REDACTED" or other strings like
   150  "****".
   151  
   152  Be sure to include the steps to reproduce the problem if applicable.
   153  It can help us understand and fix your issue faster.
   154  
   155  ## Documenting
   156  
   157  Update the documentation if you are creating or changing features. Good
   158  documentation is as important as the code itself.
   159  
   160  The main location for the documentation is the website repository. The images
   161  referred to in documents can be placed in docs/img in that repo.
   162  
   163  Documents are written with Markdown. See Writing on GitHub for more details.
   164  
   165  ## Design New Features
   166  
   167  You can propose new designs for existing zot features. You can also design
   168  entirely new features, Please submit a proposal in GitHub issues. zot
   169  maintainers will review this proposal as soon as possible. This is necessary to
   170  ensure the overall architecture is consistent and to avoid duplicated work in
   171  the roadmap.