You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2022/03/09 06:14:26 UTC
[GitHub] [apisix-ingress-controller] bin-ya opened a new pull request #909: docs: merge contribute.md and development.md
bin-ya opened a new pull request #909:
URL: https://github.com/apache/apisix-ingress-controller/pull/909
<!-- Please answer these questions before submitting a pull request -->
### Type of change:
<!-- Please delete options that are not relevant. -->
### What this PR does / why we need it:
<!--- Why is this change required? What problem does it solve? -->
<!--- If it fixes an open issue, please link to the issue here. -->
Resolves #905
### Pre-submission checklist:
<!--
Please follow the requirements:
1. Use Draft if the PR is not ready to be reviewed
2. Test is required for the feat/fix PR, unless you have a good reason
3. Doc is required for the feat PR
4. Use a new commit to resolve review instead of `push -f`
5. Use "request review" to notify the reviewer once you have resolved the review
-->
* [x] Did you explain what problem does this PR solve? Or what new features have been added?
* [ ] Have you added corresponding test cases?
* [x] Have you modified the corresponding document?
* [x] Is this PR backward compatible? **If it is not backward compatible, please discuss on the [mailing list](https://github.com/apache/apisix-ingress-controller#community) first**
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-ingress-controller] bin-ya commented on a change in pull request #909: docs: merge contribute.md and development.md
Posted by GitBox <gi...@apache.org>.
bin-ya commented on a change in pull request #909:
URL: https://github.com/apache/apisix-ingress-controller/pull/909#discussion_r824538932
##########
File path: docs/en/latest/contribute.md
##########
@@ -21,23 +21,107 @@ title: Contributing to apisix-ingress-controller
#
-->
-Firstly, thanks for your interest in contributing! I hope that this will be a
-pleasant first experience for you, and that you will return to continue
-contributing.
+This document explains how to get started with developing for Apache APISIX Ingress controller.
-## How to contribute
+## Prerequisites
-Most of the contributions that we receive are code contributions, but you can
-also contribute to the documentation or simply report solid bugs
-for us to fix.
+* Install [Go 1.13](https://golang.org/dl/) or later, and we use go module to manage the go package dependencies.
+* Prepare an available Kubernetes cluster in your workstation, we recommend you to use [KIND](https://kind.sigs.k8s.io/).
+* Install Apache APISIX in Kubernetes by [Helm Chart](https://github.com/apache/apisix-helm-chart).
- For new contributors, please take a look at issues with a tag called [Good first issue](https://github.com/apache/apisix-ingress-controller/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) or [Help wanted](https://github.com/apache/apisix-ingress-controller/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).
+## Fork and Clone
-## How to report a bug
+* Fork the repository from [apache/apisix-ingress-controller](https://github.com/apache/apisix-ingress-controller) to your own GitHub account.
+* Clone the fork repository to your workstation.
+* Run `go mod download` to download modules to local cache. By the way, if you are a developer in China, we suggest you setting `GOPROXY` to `https://goproxy.cn` to speed up the downloading.
-* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/apache/apisix-ingress-controller/issues).
+## Build
-* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/apache/apisix-ingress-controller/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring.
+```shell
+cd /path/to/apisix-ingress-controller
+make build
+./apisix-ingress-controller version
+```
+
+## Test
+
+### Run unit test cases
+
+```shell
+cd /path/to/apisix-ingress-controller
+make unit-test
+```
+
+### Run e2e test cases
+
+We using [KIND](https://kind.sigs.k8s.io/) for running e2e test cases. Please ensure `kind` CLI has been installed.
+Currently we using KIND latest version v0.11.1 and using Kubernetes v1.21.1 for testing.
+
+```shell
+cd /path/to/apisix-ingress-controller
+make e2e-test
+```
+
+Note the running of e2e cases is somewhat slow, so please be patient.
+
+> See [here](https://onsi.github.io/ginkgo/#focused-specs) to learn
+how to just run partial e2e cases.
+
+### Build docker image
+
+```shell
+cd /path/to/apisix-ingress-controller
+make build-image IMAGE_TAG=a.b.c
+```
+
+> Note: The Dockerfile in this repository is only for development, not for release.
+
+If you're coding for apisix-ingress-controller and adding some e2e test cases to verify your changes,
+you should push the images to the image registry that your Kubernetes cluster can access, if you're using Kind, just run the following command:
+
+```shell
+make push-images-to-kind
+```
+
+## Run apisix-ingress-controller locally
+
+We assume all prerequisites above mentioned are met, what's more, since we want to run apisix-ingress-controller in bare-metal environment, please make sure both the proxy service and admin api service of Apache APISIX are exposed outside of the Kubernetes cluster, e.g. configuring them as [NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#nodeport) services.
+
+Let's assume the Admin API service address of Apache APISIX is `http://192.168.65.2:31156`. Next launch the ingress-apisix-controller by the following command.
+
+```shell
+cd /path/to/apisix-ingress-controller
+./apisix-ingress-controller ingress \
+ --kubeconfig /path/to/kubeconfig \
+ --http-listen :8080 \
+ --log-output stderr \
+ --default-apisix-cluster-base-url http://192.168.65.2:31156/apisix/admin
+ --default-apisix-cluster-admin-key edd1c9f034335f136f87ad84b625c8f1
+```
+
+Something you need to pay attention to:
+
+* configuring of `--kubeconfig`, if you are using Minikube, the file path should be `~/.kube/config`.
+* configuring of `--default-apisix-cluster-admin-key`, if you have changed the admin key in Apache APISIX, also changing it here. If you have disabled the authentication in Apache APISIX, just removing this option.
+
+## Pre-commit todo
+
+When everything is ready, before submitting the code, please make sure that the license, code style, and document format are consistent with the project specification.
+
+We provide commands to implement it, just run the following commands:
+
+```shell
+make update-codegen
+make update-license
+make update-gofmt
+make update-mdlint
+```
+
+or just run one command:
+
+```shell
+make update-all
+```
## How to add a new feature or change an existing one
Review comment:
Line 122 to 124 or the paragraph Pre-commit todo?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-ingress-controller] tao12345666333 commented on pull request #909: docs: merge contribute.md and development.md
Posted by GitBox <gi...@apache.org>.
tao12345666333 commented on pull request #909:
URL: https://github.com/apache/apisix-ingress-controller/pull/909#issuecomment-1062616925
Please check the CI errors.
You can run `make update-mdlint` locally.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-ingress-controller] lijing-21 commented on pull request #909: docs: merge contribute.md and development.md
Posted by GitBox <gi...@apache.org>.
lijing-21 commented on pull request #909:
URL: https://github.com/apache/apisix-ingress-controller/pull/909#issuecomment-1068995765
Hi @bin-ya , thank you for your contribution!
Here is the Contributor T-shirt form[1], if you're interested, kindly take a look :)
[1] https://github.com/apache/apisix/blob/master/CONTRIBUTING.md#contributor-t-shirt
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-ingress-controller] tao12345666333 merged pull request #909: docs: merge contribute.md and development.md
Posted by GitBox <gi...@apache.org>.
tao12345666333 merged pull request #909:
URL: https://github.com/apache/apisix-ingress-controller/pull/909
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-ingress-controller] lingsamuel commented on a change in pull request #909: docs: merge contribute.md and development.md
Posted by GitBox <gi...@apache.org>.
lingsamuel commented on a change in pull request #909:
URL: https://github.com/apache/apisix-ingress-controller/pull/909#discussion_r824339366
##########
File path: docs/en/latest/contribute.md
##########
@@ -21,23 +21,107 @@ title: Contributing to apisix-ingress-controller
#
-->
-Firstly, thanks for your interest in contributing! I hope that this will be a
-pleasant first experience for you, and that you will return to continue
-contributing.
+This document explains how to get started with developing for Apache APISIX Ingress controller.
-## How to contribute
+## Prerequisites
-Most of the contributions that we receive are code contributions, but you can
-also contribute to the documentation or simply report solid bugs
-for us to fix.
+* Install [Go 1.13](https://golang.org/dl/) or later, and we use go module to manage the go package dependencies.
+* Prepare an available Kubernetes cluster in your workstation, we recommend you to use [KIND](https://kind.sigs.k8s.io/).
+* Install Apache APISIX in Kubernetes by [Helm Chart](https://github.com/apache/apisix-helm-chart).
- For new contributors, please take a look at issues with a tag called [Good first issue](https://github.com/apache/apisix-ingress-controller/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) or [Help wanted](https://github.com/apache/apisix-ingress-controller/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).
+## Fork and Clone
-## How to report a bug
+* Fork the repository from [apache/apisix-ingress-controller](https://github.com/apache/apisix-ingress-controller) to your own GitHub account.
+* Clone the fork repository to your workstation.
+* Run `go mod download` to download modules to local cache. By the way, if you are a developer in China, we suggest you setting `GOPROXY` to `https://goproxy.cn` to speed up the downloading.
-* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/apache/apisix-ingress-controller/issues).
+## Build
-* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/apache/apisix-ingress-controller/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring.
+```shell
+cd /path/to/apisix-ingress-controller
+make build
+./apisix-ingress-controller version
+```
+
+## Test
+
+### Run unit test cases
+
+```shell
+cd /path/to/apisix-ingress-controller
+make unit-test
+```
+
+### Run e2e test cases
+
+We using [KIND](https://kind.sigs.k8s.io/) for running e2e test cases. Please ensure `kind` CLI has been installed.
+Currently we using KIND latest version v0.11.1 and using Kubernetes v1.21.1 for testing.
+
+```shell
+cd /path/to/apisix-ingress-controller
+make e2e-test
+```
+
+Note the running of e2e cases is somewhat slow, so please be patient.
+
+> See [here](https://onsi.github.io/ginkgo/#focused-specs) to learn
+how to just run partial e2e cases.
+
+### Build docker image
+
+```shell
+cd /path/to/apisix-ingress-controller
+make build-image IMAGE_TAG=a.b.c
+```
+
+> Note: The Dockerfile in this repository is only for development, not for release.
+
+If you're coding for apisix-ingress-controller and adding some e2e test cases to verify your changes,
+you should push the images to the image registry that your Kubernetes cluster can access, if you're using Kind, just run the following command:
+
+```shell
+make push-images-to-kind
+```
+
+## Run apisix-ingress-controller locally
+
+We assume all prerequisites above mentioned are met, what's more, since we want to run apisix-ingress-controller in bare-metal environment, please make sure both the proxy service and admin api service of Apache APISIX are exposed outside of the Kubernetes cluster, e.g. configuring them as [NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#nodeport) services.
+
+Let's assume the Admin API service address of Apache APISIX is `http://192.168.65.2:31156`. Next launch the ingress-apisix-controller by the following command.
+
+```shell
+cd /path/to/apisix-ingress-controller
+./apisix-ingress-controller ingress \
+ --kubeconfig /path/to/kubeconfig \
+ --http-listen :8080 \
+ --log-output stderr \
+ --default-apisix-cluster-base-url http://192.168.65.2:31156/apisix/admin
+ --default-apisix-cluster-admin-key edd1c9f034335f136f87ad84b625c8f1
+```
+
+Something you need to pay attention to:
+
+* configuring of `--kubeconfig`, if you are using Minikube, the file path should be `~/.kube/config`.
+* configuring of `--default-apisix-cluster-admin-key`, if you have changed the admin key in Apache APISIX, also changing it here. If you have disabled the authentication in Apache APISIX, just removing this option.
+
+## Pre-commit todo
+
+When everything is ready, before submitting the code, please make sure that the license, code style, and document format are consistent with the project specification.
+
+We provide commands to implement it, just run the following commands:
+
+```shell
+make update-codegen
+make update-license
+make update-gofmt
+make update-mdlint
+```
+
+or just run one command:
+
+```shell
+make update-all
+```
## How to add a new feature or change an existing one
Review comment:
I think it would be better to put this section before `test`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-ingress-controller] tao12345666333 commented on pull request #909: docs: merge contribute.md and development.md
Posted by GitBox <gi...@apache.org>.
tao12345666333 commented on pull request #909:
URL: https://github.com/apache/apisix-ingress-controller/pull/909#issuecomment-1063762847
> development.md after renaming, there are three files containing development.md. Can I modify it?(README.md line 92, CHANGELOG.md line 419, getting-started.md line 70)
Sure, please!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-ingress-controller] lingsamuel commented on a change in pull request #909: docs: merge contribute.md and development.md
Posted by GitBox <gi...@apache.org>.
lingsamuel commented on a change in pull request #909:
URL: https://github.com/apache/apisix-ingress-controller/pull/909#discussion_r826494974
##########
File path: docs/en/latest/contribute.md
##########
@@ -21,23 +21,107 @@ title: Contributing to apisix-ingress-controller
#
-->
-Firstly, thanks for your interest in contributing! I hope that this will be a
-pleasant first experience for you, and that you will return to continue
-contributing.
+This document explains how to get started with developing for Apache APISIX Ingress controller.
-## How to contribute
+## Prerequisites
-Most of the contributions that we receive are code contributions, but you can
-also contribute to the documentation or simply report solid bugs
-for us to fix.
+* Install [Go 1.13](https://golang.org/dl/) or later, and we use go module to manage the go package dependencies.
+* Prepare an available Kubernetes cluster in your workstation, we recommend you to use [KIND](https://kind.sigs.k8s.io/).
+* Install Apache APISIX in Kubernetes by [Helm Chart](https://github.com/apache/apisix-helm-chart).
- For new contributors, please take a look at issues with a tag called [Good first issue](https://github.com/apache/apisix-ingress-controller/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) or [Help wanted](https://github.com/apache/apisix-ingress-controller/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).
+## Fork and Clone
-## How to report a bug
+* Fork the repository from [apache/apisix-ingress-controller](https://github.com/apache/apisix-ingress-controller) to your own GitHub account.
+* Clone the fork repository to your workstation.
+* Run `go mod download` to download modules to local cache. By the way, if you are a developer in China, we suggest you setting `GOPROXY` to `https://goproxy.cn` to speed up the downloading.
-* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/apache/apisix-ingress-controller/issues).
+## Build
-* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/apache/apisix-ingress-controller/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring.
+```shell
+cd /path/to/apisix-ingress-controller
+make build
+./apisix-ingress-controller version
+```
+
+## Test
+
+### Run unit test cases
+
+```shell
+cd /path/to/apisix-ingress-controller
+make unit-test
+```
+
+### Run e2e test cases
+
+We using [KIND](https://kind.sigs.k8s.io/) for running e2e test cases. Please ensure `kind` CLI has been installed.
+Currently we using KIND latest version v0.11.1 and using Kubernetes v1.21.1 for testing.
+
+```shell
+cd /path/to/apisix-ingress-controller
+make e2e-test
+```
+
+Note the running of e2e cases is somewhat slow, so please be patient.
+
+> See [here](https://onsi.github.io/ginkgo/#focused-specs) to learn
+how to just run partial e2e cases.
+
+### Build docker image
+
+```shell
+cd /path/to/apisix-ingress-controller
+make build-image IMAGE_TAG=a.b.c
+```
+
+> Note: The Dockerfile in this repository is only for development, not for release.
+
+If you're coding for apisix-ingress-controller and adding some e2e test cases to verify your changes,
+you should push the images to the image registry that your Kubernetes cluster can access, if you're using Kind, just run the following command:
+
+```shell
+make push-images-to-kind
+```
+
+## Run apisix-ingress-controller locally
+
+We assume all prerequisites above mentioned are met, what's more, since we want to run apisix-ingress-controller in bare-metal environment, please make sure both the proxy service and admin api service of Apache APISIX are exposed outside of the Kubernetes cluster, e.g. configuring them as [NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#nodeport) services.
+
+Let's assume the Admin API service address of Apache APISIX is `http://192.168.65.2:31156`. Next launch the ingress-apisix-controller by the following command.
+
+```shell
+cd /path/to/apisix-ingress-controller
+./apisix-ingress-controller ingress \
+ --kubeconfig /path/to/kubeconfig \
+ --http-listen :8080 \
+ --log-output stderr \
+ --default-apisix-cluster-base-url http://192.168.65.2:31156/apisix/admin
+ --default-apisix-cluster-admin-key edd1c9f034335f136f87ad84b625c8f1
+```
+
+Something you need to pay attention to:
+
+* configuring of `--kubeconfig`, if you are using Minikube, the file path should be `~/.kube/config`.
+* configuring of `--default-apisix-cluster-admin-key`, if you have changed the admin key in Apache APISIX, also changing it here. If you have disabled the authentication in Apache APISIX, just removing this option.
+
+## Pre-commit todo
+
+When everything is ready, before submitting the code, please make sure that the license, code style, and document format are consistent with the project specification.
+
+We provide commands to implement it, just run the following commands:
+
+```shell
+make update-codegen
+make update-license
+make update-gofmt
+make update-mdlint
+```
+
+or just run one command:
+
+```shell
+make update-all
+```
## How to add a new feature or change an existing one
Review comment:
I mean the "How to add a new feature or change an existing one" section, sorry.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-ingress-controller] bin-ya commented on pull request #909: docs: merge contribute.md and development.md
Posted by GitBox <gi...@apache.org>.
bin-ya commented on pull request #909:
URL: https://github.com/apache/apisix-ingress-controller/pull/909#issuecomment-1063584826
> 请检查 CI 错误。 您可以在`make update-mdlint`本地运行。
development.md after renaming, there are three files containing development.md. Can I modify it?(README.md line 92, CHANGELOG.md line 419, getting-started.md line 70)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-ingress-controller] tao12345666333 commented on a change in pull request #909: docs: merge contribute.md and development.md
Posted by GitBox <gi...@apache.org>.
tao12345666333 commented on a change in pull request #909:
URL: https://github.com/apache/apisix-ingress-controller/pull/909#discussion_r822319625
##########
File path: README.md
##########
@@ -126,3 +126,17 @@ We welcome all kinds of contributions from the open-source community, individual
## License
[Apache License 2.0](https://github.com/apache/apisix-ingress-controller/blob/master/LICENSE)
+
+## How to contribute
+
+Most of the contributions that we receive are code contributions, but you can
+also contribute to the documentation or simply report solid bugs
+for us to fix.
+
+ For new contributors, please take a look at issues with a tag called [Good first issue](https://github.com/apache/apisix-ingress-controller/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) or [Help wanted](https://github.com/apache/apisix-ingress-controller/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).
+
+ ## How to report a bug
Review comment:
Please remove spaces
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org