Skip to content

Commit

Permalink
chore: Update developer guide docs (argoproj#4664)
Browse files Browse the repository at this point in the history 
- Remove references to CircleCI
- Move info for troubleshooting CI builds into ci.md
- Add 'gofmt' note to Lint CI check failing
- Add note about generated code to FAQ

Signed-off-by: Tim Etchells <tetchell@redhat.com>
  • Loading branch information
@tetchel
tetchel authored Oct 26, 2020
1 parent 3d39acc commit ac8d18d
Show file tree
Hide file tree
Showing 3 changed files with 49 additions and 61 deletions.
Binary file modified docs/developer-guide/ci-pipeline-failed.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
55 changes: 38 additions & 17 deletions docs/developer-guide/ci.md
View file
Original file line number Diff line number Diff line change
@@ -1,31 +1,52 @@
# CI
# Continuous Integration (CI)

!!!warning
This documentation is out-of-date. Please bear with us while we work to
update the documentation to reflect reality!
## Troubleshooting CI checks

## Troubleshooting Builds
You can click on the "Details" link next to the failed step to get more information about the failure.

### "Check nothing has changed" step fails

If your PR fails the `codegen` CI step, you can either:
![Failed GitHub Action](ci-pipeline-failed.png)

(1) Simple - download the `codgen.patch` file from CircleCI and apply it:
To read more about The GitHub actions are configured in [`ci-build.yaml`](https://github.com/argoproj/argo-cd/blob/master/.github/workflows/ci-build.yaml).

![download codegen patch file](../assets/download-codegen-patch-file.png)
### Can I retrigger the checks without pushing a new commit?

```bash
git apply codegen.patch
git commit -am "Applies codegen patch"
```
Since the CI pipeline is triggered on Git commits, there is currently no (known) way on how to retrigger the CI checks without pushing a new commit to your branch.

(2) Advanced - if you have the tools installed (see the contributing guide), run the following:
If you are absolutely sure that the failure was due to a failure in the pipeline, and not an error within the changes you commited, you can push an empty commit to your branch, thus retriggering the pipeline without any code changes. To do so, issue

```bash
make pre-commit
git commit -am 'Ran pre-commit checks'
git commit --allow-empty -m "Retrigger CI pipeline"
git push origin <yourbranch>
```

### Why does the build step fail?

First, make sure the failing build step succeeds on your machine. Remember the containerized build toolchain is available, too.

If the build is failing at the `Ensuring Gopkg.lock is up-to-date` step, you need to update the dependencies before you push your commits. Run `make dep-ensure` and `make dep` and commit the changes to `Gopkg.lock` to your branch.

### Why does the codegen step fail?

If the codegen step fails with "Check nothing has changed...", chances are high that you did not run `make codegen`, or did not commit the changes it made. You should double check by running `make codegen` followed by `git status` in the local working copy of your branch. Commit any changes and push them to your GH branch to have the CI check it again.

A second common case for this is, when you modified any of the auto generated assets, as these will be overwritten upon `make codegen`.

Generally, this step runs `codegen` and compares the outcome against the Git branch it has checked out. If there are differences, the step will fail.

See [What checked-in code is generated and where does it come from?](faq#what-checked-in-code-is-generated-and-how-is-it-generated) for more information.

### Why does the lint step fail?

Your code failed to lint correctly, or modifications were performed by the `golangci-lint` process.

* You should run `make lint`, or `golangci-lint run` on your local branch and fix all the issues.

* If you receive an error like, ```File is not `goimports`-ed (goimports)```, the file is not formatted correctly. Run `gofmt -w $file.go` to resolve this linter error.

### Why does the test or e2e steps fail?

You should check for the cause of the failure in the check's detail page as described above. This will give you the name of the test that has failed, and details about why. If your test are passing locally (using the virtualized toolchain), chances are that the test might be flaky and will pass the next time it is run. Please retrigger the CI pipeline as described above and see if the test step now passes.

## Updating The Builder Image

Login to Docker Hub:
Expand Down
55 changes: 11 additions & 44 deletions docs/developer-guide/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,50 +16,17 @@ We appreciate that you have put your valuable time and know how into a contribut

To be on the safe side, make sure that you have created an Enhancement Proposal for your change before starting to work on your PR and have gathered enough feedback from the community and the maintainers.

## Failing CI checks
### A check on my PR is failing.
See [Failing CI Checks](ci.md#troubleshooting-ci-checks).

### One of the CI checks failed. Why?
### What checked-in code is generated, and how is it generated?
The following files under this repository are generated, and must be kept up-to-date. Also see [Why does the codegen step fail?](ci#why-does-the-codegen-step-fail).

You can click on the "Details" link next to the failed step to get more details about the failure. This will take you to CircleCI website.
See the Makefile for targets that can also run these scripts, and the `codegen` target which runs them all.

![CircleCI pipeline](ci-pipeline-failed.png)

### Can I retrigger the checks without pushing a new commit?

Since the CI pipeline is triggered on Git commits, there is currently no (known) way on how to retrigger the CI checks without pushing a new commit to your branch.

If you are absolutely sure that the failure was due to a failure in the pipeline, and not an error within the changes you commited, you can push an empty commit to your branch, thus retriggering the pipeline without any code changes. To do so, issue

```bash
git commit --allow-empty -m "Retrigger CI pipeline"
git push origin <yourbranch>
```

### Why does the build step fail?

Chances are that it fails for two of the following reasons in the CI while running fine on your machine:

* Sometimes, CircleCI kills the build step due to excessive memory usage. This happens rarely, but it has happened in the past. If you see a message like "killed" in the log output of CircleCI, you should retrigger the pipeline as described above. If the issue persists, please let us know.

* If the build is failing at the `Ensuring Gopkg.lock is up-to-date` step, you need to update the dependencies before you push your commits. Run `make dep-ensure` and `make dep` and commit the changes to `Gopkg.lock` to your branch.

### Why does the codegen step fail?

If the codegen step fails with "Check nothing has changed...", chances are high that you did not run `make codegen`, or did not commit the changes it made. You should double check by running `make codegen` followed by `git status` in the local working copy of your branch. Commit any changes and push them to your GH branch to have the CI check it again.

A second common case for this is, when you modified any of the auto generated assets, as these will be overwritten upon `make codegen`.

Generally, this step runs `codegen` and compares the outcome against the Git branch it has checked out. If there are differences, the step will fail.

### Why does the lint step fail?

The lint step is most likely to fail for two reasons:

* The `golangci-lint` process was OOM killed by CircleCI. This happens sometimes, and is annoying. This is indicated by a `Killed.` message in the CircleCI output.
If this is the case, please re-trigger the CI process as described above and see if it runs through.

* Your code failed to lint correctly, or modifications were performed by the `golangci-lint` process. You should run `make lint` on your local branch and fix all the issues.

### Why does the test or e2e steps fail?

You should check for the cause of the failure on the CircleCI web site, as described above. This will give you the name of the test that has failed, and details about why. If your test are passing locally (using the virtualized toolchain), chances are that the test might be flaky and will pass the next time it is run. Please retrigger the CI pipeline as described above and see if the test step now passes.
| Filename | Purpose | Generated by |
| -------- | ------- | ------------ |
| `*.pb.go`, `*.pb.gw.go` | [Protobuf](https://developers.google.com/protocol-buffers/docs/gotutorial) Interfaces | `hack/generate-proto.sh` |
| `assets/swagger.json` | Swagger 2 API spec | `hack/update-openapi.sh` |
| `manifests/` | k8s Installation Manifests | `hack/update-manifests.sh` |
| `docs/user-guide/commands` | CLI Documentation | `tools/cmd-docs/main.go` |

0 comments on commit ac8d18d

Please sign in to comment.