You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by lb...@apache.org on 2018/09/11 20:02:33 UTC
[camel-k] branch master updated (bff423d -> 15cd1e5)
This is an automated email from the ASF dual-hosted git repository.
lburgazzoli pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/camel-k.git.
from bff423d Bump Camel to version 2.22.1
new 0fc767a Adding contributing guide
new 15cd1e5 Fix typos in contributing guide
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
README.md | 153 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 142 insertions(+), 11 deletions(-)
[camel-k] 01/02: Adding contributing guide
Posted by lb...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
lburgazzoli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel-k.git
commit 0fc767a608ef7435e3bd8c6f741c49fcd44c3531
Author: nferraro <ni...@gmail.com>
AuthorDate: Tue Sep 11 18:47:32 2018 +0200
Adding contributing guide
---
README.md | 153 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 142 insertions(+), 11 deletions(-)
diff --git a/README.md b/README.md
index 43c0db8..fe6c33b 100644
--- a/README.md
+++ b/README.md
@@ -35,7 +35,7 @@ Minikube and Kubernetes are not yet supported (but support is coming soon).
To start using Camel K you need the **"kamel"** binary, that can be used to both configure the cluster and run integrations.
-There's currently no release channel for the "kamel" binary, so you need to **build it from source!** Refer to the [building section](#building)
+There's currently no release channel for the "kamel" binary, so you need to **build it from source!** Refer to the [contributing guide](#contributing)
for information on how to do it.
Once you have the "kamel" binary, log into your cluster using the "oc" or "kubectl" tool and execute the following command to install Camel K:
@@ -69,19 +69,150 @@ You can check the status of all integrations by executing the following command:
kamel get
```
-### Uninstalling Camel K
+## Contributing
-If requires to uninstall Camel K from the OpenShift or Kubernetes, it's nessesary to run following command using "oc" or "kubectl" tool:
+We love contributions!
+
+The project is written in [Go](https://golang.org/) and contains some parts written in Java for the [integration runtime](/runtime).
+Camel K is built on top of Kubernetes through *Custom Resource Definitions*. The [Operator SDK](https://github.com/operator-framework/operator-sdk) is used
+to manage the lifecycle of those custom resources.
+
+### Requirements
+
+In order to build the project, you need to comply with the following requirements:
+- **Go version 1.10+**: needed to compile and test the project. Refer to the [Go website](https://golang.org/) for the installation.
+- **Dep version 0.5.0**: for managing dependencies. You can find installation instructions in the [dep GitHub repository](https://github.com/golang/dep).
+- **Operator SDK v0.0.6+**: used to build the operator and the Docker images. Instructions in the [Operator SDK website](https://github.com/operator-framework/operator-sdk).
+- **GNU Make**: used to define composite build actions. This should be already installed or available as package if you have a good OS (https://www.gnu.org/software/make/).
+
+### Checking Out the Sources
+
+You can create a fork of this project from Github, then clone your fork with the `git` command line tool.
+
+You need to put the project in your $GOPATH (refer to [Go documentation](https://golang.org/doc/install) for information).
+So, make sure that the **root** of the github repo is in the path:
```
-delete all,pvc,configmap,rolebindings,clusterrolebindings,secrets,sa,roles,clusterroles,crd -l 'app=camel-k'
+$GOPATH/src/github.com/apache/camel-k/
```
-## Building
+### Structure
+
+This is a high level overview of the project structure:
+
+- [/cmd](/cmd): contains the entry points (the *main* function) for the **camel-k-operator** binary and the **kamel** client tool.
+- [/build](/build): contains scripts used during make operations for building the project.
+- [/deploy](/deploy): contains Kubernetes resource files that are used by the **kamel** client during installation. The `/deploy/resources.go` file is kept in sync with the content of the directory (`make build-embed-resources`), so that resources can be used from within the go code.
+- [/pkg](/pkg): this is where the code resides. The code is divided in multiple subpackages.
+- [/runtime](/runtime): the Java runtime code that is used inside the integration Docker containers.
+- [/tmp](/tmp): scripts and Docker configuration files used by the operator-sdk.
+- [/vendor](/vendor): project dependencies.
+- [/version](/version): contains the global version of the project.
+
+### Building
+
+Go dependencies in the *vendor* directory are not included when you clone the project.
+
+Before compiling the source code, you need to sync your local *vendor* directory with the project dependencies, using the following command:
+
+```
+make dep
+```
+
+The `make dep` command runs `dep ensure -v` under the hood, so make sure that `dep` is properly installed.
+
+To build the whole project you now need to run:
+
+```
+make
+```
+
+This execute a full build of both the Java and Go code. If you need to build the components separately you can execute:
+- `make build-operator`: to build the operator binary only.
+- `make build-kamel`: to build the `kamel` client tool only.
+- `make build-runtime`: to build the Java-based runtime code only.
+
+After a successful build, if you're connected to a Docker daemon, you can build the operator Docker image by running:
+
+```
+make images
+```
+
+### Testing
+
+Unit tests are executed automatically as part of the build. They use the standard go testing framework.
+
+Integration tests (aimed at ensuring that the code integrates correctly with Kubernetes and Openshift), need special care.
+
+The **convention** used in this repo is to name unit tests `xxx_test.go`, and name integration tests `yyy_integration_test.go`.
+
+Since both names end with `_test.go`, both would be executed by go during build, so you need to put a special **build tag** to mark
+integration tests. A integration test should start with the following line:
+
+```
+// +build integration
+```
-In order to build the project follow these steps:
-- this project is supposed to be cloned in `$GOPATH/src/github.com/apache/camel-k`
-- install dep: https://github.com/golang/dep The last version is 0.5.0 and it's requested to use this version to be able to be aligned on each build.
-- install operator-sdk: https://github.com/operator-framework/operator-sdk
-- dep ensure -v
-- make build
+An [example is provided here](https://github.com/apache/camel-k/blob/ff672fbf54c358fca970da6c59df378c8535d4d8/pkg/build/build_manager_integration_test.go#L1).
+
+Before running a integration test, you need to:
+- Login to a Kubernetes/Openshift cluster.
+- Set the `KUBERNETES_CONFIG` environment variable to point to your Kubernetes configuration file (usually `<home-dir>/.kube/config`).
+- Set the `WATCH_NAMESPACE` environment variable to a Kubernetes namespace you have access to.
+- Set the `OPERATOR_NAME` environment variable to `camel-k-operator`.
+
+When the configuration is done, you can run the following command to execute **all** integration tests:
+
+```
+make test-integration
+```
+
+### Running
+
+If you want to install everything you have in your source code and see it running on Kubernetes, you need to follow these steps:
+- `make`: to build the project.
+- `eval $(minishift docker-env)`: to connect to your Minishift Docker daemon.
+- `make images`: to build the operator docker image.
+- `./kamel install`: to install Camel K into the namespace.
+- `oc delete pod -l name=camel-k-operator`: to ensure the operator is using latest image (delete the pod to let Openshift recreate it).
+
+**Note for contributors:** why don't you embed all those steps in a `make install-minishift` command?
+
+Now you can play with Camel K:
+
+```
+kamel run Sample.java
+```
+
+### Debugging and Running from IDE
+
+Sometimes it's useful to debug the code from the IDE when troubleshooting.
+
+**Debugging the `kamel` binary**
+
+It should be straightforward: just execute the [/cmd/kamel/kamel.go]([/cmd/kamel/kamel.go]) file from the IDE (e.g. Goland) in debug mode.
+
+**Debugging the operator**
+
+It is a bit more complex (but not so much).
+
+You are going to run the operator code **outside** Openshift in your IDE so, first of all, you need to **stop the operator running inside**:
+
+```
+oc scale deployment/camel-k-operator --replicas 0
+```
+
+You can scale it back to 1 when you're done and you have updated the operator image.
+
+You can setup the IDE to execute the [/cmd/camel-k-operator/camel_k_operator.go]([/cmd/camel-k-operator/camel_k_operator.go]) file from the IDE (e.g. Goland) in debug mode.
+
+When configuring the IDE task, make sure to add all required environment variables (such as `KUBERNETES_CONFIG`, as explained in the [testing](#testing) section) in
+the IDE task configuration.
+
+## Uninstalling Camel K
+
+If required, it is possible to uninstall Camel K from OpenShift or Kubernetes with the following command using the "oc" or "kubectl" tool:
+
+```
+delete all,pvc,configmap,rolebindings,clusterrolebindings,secrets,sa,roles,clusterroles,crd -l 'app=camel-k'
+```
[camel-k] 02/02: Fix typos in contributing guide
Posted by lb...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
lburgazzoli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel-k.git
commit 15cd1e5d74a48e6f6c2d04bbc93497ea0e56eb58
Author: nferraro <ni...@gmail.com>
AuthorDate: Tue Sep 11 18:58:29 2018 +0200
Fix typos in contributing guide
---
README.md | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/README.md b/README.md
index fe6c33b..7d9b496 100644
--- a/README.md
+++ b/README.md
@@ -100,7 +100,7 @@ $GOPATH/src/github.com/apache/camel-k/
This is a high level overview of the project structure:
-- [/cmd](/cmd): contains the entry points (the *main* function) for the **camel-k-operator** binary and the **kamel** client tool.
+- [/cmd](/cmd): contains the entry points (the *main* functions) for the **camel-k-operator** binary and the **kamel** client tool.
- [/build](/build): contains scripts used during make operations for building the project.
- [/deploy](/deploy): contains Kubernetes resource files that are used by the **kamel** client during installation. The `/deploy/resources.go` file is kept in sync with the content of the directory (`make build-embed-resources`), so that resources can be used from within the go code.
- [/pkg](/pkg): this is where the code resides. The code is divided in multiple subpackages.
@@ -181,7 +181,7 @@ If you want to install everything you have in your source code and see it runnin
Now you can play with Camel K:
```
-kamel run Sample.java
+./kamel run Sample.java
```
### Debugging and Running from IDE
@@ -204,15 +204,15 @@ oc scale deployment/camel-k-operator --replicas 0
You can scale it back to 1 when you're done and you have updated the operator image.
-You can setup the IDE to execute the [/cmd/camel-k-operator/camel_k_operator.go]([/cmd/camel-k-operator/camel_k_operator.go]) file from the IDE (e.g. Goland) in debug mode.
+You can setup the IDE (e.g. Goland) to execute the [/cmd/camel-k-operator/camel_k_operator.go]([/cmd/camel-k-operator/camel_k_operator.go]) file in debug mode.
-When configuring the IDE task, make sure to add all required environment variables (such as `KUBERNETES_CONFIG`, as explained in the [testing](#testing) section) in
-the IDE task configuration.
+When configuring the IDE task, make sure to add all required environment variables in the *IDE task configuration screen* (such as `KUBERNETES_CONFIG`, as explained in the [testing](#testing) section).
## Uninstalling Camel K
-If required, it is possible to uninstall Camel K from OpenShift or Kubernetes with the following command using the "oc" or "kubectl" tool:
+If required, it is possible to completely uninstall Camel K from OpenShift or Kubernetes with the following command, using the "oc" or "kubectl" tool:
```
-delete all,pvc,configmap,rolebindings,clusterrolebindings,secrets,sa,roles,clusterroles,crd -l 'app=camel-k'
+# kubectl if using kubernetes
+oc delete all,pvc,configmap,rolebindings,clusterrolebindings,secrets,sa,roles,clusterroles,crd -l 'app=camel-k'
```