tysonjh commented on a change in pull request #14477: URL: https://github.com/apache/beam/pull/14477#discussion_r610784504
########## File path: website/www/site/content/en/contribute/_index.md ########## @@ -73,20 +73,33 @@ detail. ### Prerequisites - - a GitHub account - - a Linux, macOS, or Microsoft Windows development environment with Java JDK 8 installed - - [Docker](https://www.docker.com/) installed for some tasks including building worker containers and testing this website - changes locally - - [Go](https://golang.org) 1.12 or later installed for Go SDK development + - A GitHub account. + - A Linux, macOS, or Microsoft Windows development environment + - Required *only* For Windows: Review comment: I thought Java and Docker were required for all operating systems? E.g. the manual steps below include installing JAva 8. ########## File path: website/www/site/content/en/contribute/_index.md ########## @@ -73,20 +73,33 @@ detail. ### Prerequisites - - a GitHub account - - a Linux, macOS, or Microsoft Windows development environment with Java JDK 8 installed - - [Docker](https://www.docker.com/) installed for some tasks including building worker containers and testing this website - changes locally - - [Go](https://golang.org) 1.12 or later installed for Go SDK development + - A GitHub account. + - A Linux, macOS, or Microsoft Windows development environment + - Required *only* For Windows: + - Java JDK 8 installed + - [Docker](https://www.docker.com/) installed for some tasks including building worker containers and testing this website + changes locally. + - For SDK Development: + - [Go](https://golang.org) 1.12 or later installed for Go SDK development - Python 3.6, 3.7, and 3.8. Yes, you need all three versions installed. - - pip, setuptools, virtualenv, and tox installed for Python development - - for large contributions, a signed [Individual Contributor License + - Required *only* For Windows: + - pip, setuptools, virtualenv, and tox installed for Python development + - For large contributions, a signed [Individual Contributor License Agreement](https://www.apache.org/licenses/icla.pdf) (ICLA) to the Apache Software Foundation (ASF). +### Configuration options +You have two options for configuring your development environment: +- Local: Debian-based Distribution + - Manual steps + - Automated script (*only* for Linux and macOS) +- Container: Docker-based Review comment: ```suggestion You have two options for configuring your development environment: - Local: - Manually installing the prerequisites listed above. - Using the automated script for Linux and macOS. - Container: using a Docker image. ``` ########## File path: website/www/site/content/en/contribute/_index.md ########## @@ -73,20 +73,33 @@ detail. ### Prerequisites - - a GitHub account - - a Linux, macOS, or Microsoft Windows development environment with Java JDK 8 installed - - [Docker](https://www.docker.com/) installed for some tasks including building worker containers and testing this website - changes locally - - [Go](https://golang.org) 1.12 or later installed for Go SDK development + - A GitHub account. + - A Linux, macOS, or Microsoft Windows development environment + - Required *only* For Windows: + - Java JDK 8 installed + - [Docker](https://www.docker.com/) installed for some tasks including building worker containers and testing this website + changes locally. + - For SDK Development: + - [Go](https://golang.org) 1.12 or later installed for Go SDK development - Python 3.6, 3.7, and 3.8. Yes, you need all three versions installed. - - pip, setuptools, virtualenv, and tox installed for Python development - - for large contributions, a signed [Individual Contributor License + - Required *only* For Windows: + - pip, setuptools, virtualenv, and tox installed for Python development + - For large contributions, a signed [Individual Contributor License Agreement](https://www.apache.org/licenses/icla.pdf) (ICLA) to the Apache Software Foundation (ASF). +### Configuration options +You have two options for configuring your development environment: +- Local: Debian-based Distribution + - Manual steps + - Automated script (*only* for Linux and macOS) +- Container: Docker-based +#### Local: Debian-based Distribution +##### Manual steps Review comment: I'm not sure that we should list manual steps here. I'd like some input from others in the community on this though to confirm. /cc @TheNeuralBit @griscz @ajamato Since we're listing the prerequisites above, users can install them based on whatever OS tools they want. We also link to the installation script, which a user could either use or reference. ########## File path: website/www/site/content/en/contribute/_index.md ########## @@ -73,20 +73,33 @@ detail. ### Prerequisites - - a GitHub account - - a Linux, macOS, or Microsoft Windows development environment with Java JDK 8 installed - - [Docker](https://www.docker.com/) installed for some tasks including building worker containers and testing this website - changes locally - - [Go](https://golang.org) 1.12 or later installed for Go SDK development + - A GitHub account. + - A Linux, macOS, or Microsoft Windows development environment + - Required *only* For Windows: + - Java JDK 8 installed + - [Docker](https://www.docker.com/) installed for some tasks including building worker containers and testing this website + changes locally. + - For SDK Development: + - [Go](https://golang.org) 1.12 or later installed for Go SDK development - Python 3.6, 3.7, and 3.8. Yes, you need all three versions installed. - - pip, setuptools, virtualenv, and tox installed for Python development - - for large contributions, a signed [Individual Contributor License + - Required *only* For Windows: Review comment: Same here. The manual steps include installing these tools. ########## File path: website/www/site/content/en/contribute/_index.md ########## @@ -151,15 +181,52 @@ script which is part of the Beam repo: ### Development Setup {#development-setup} -1. If you need help with git forking, cloning, branching, committing, pull requests, and squashing commits, see - [Git workflow tips](https://cwiki.apache.org/confluence/display/BEAM/Git+Tips) -1. Clone the git repository. You can download it anywhere you like, however for Go development we recommend putting it in your [`$GOPATH`](https://golang.org/doc/gopath_code#GOPATH) (`$HOME/go` by default on Unix systems). +1. Check [Git workflow tips](https://cwiki.apache.org/confluence/display/BEAM/Git+Tips) if you need help with git forking, cloning, branching, committing, pull requests, and squashing commits. +1. Clone the git repository. You can download it anywhere you like. $ mkdir -p ~/go/src/github.com/apache $ cd ~/go/src/github.com/apache $ git clone https://github.com/apache/beam $ cd beam + - For Go development: + We recommend putting it in your [`$GOPATH`](https://golang.org/doc/gopath_code#GOPATH) (`$HOME/go` by default on Unix systems). + 1. Clone the repo, and update your branch as normal + $ git clone https://github.com/apache/beam.git + $ cd beam + $ git remote add <GitHub_user> [email protected]:<GitHub_user>/beam.git + $ git fetch --all + 1. Get or Update all the Go SDK dependencies + $ go get -u ./... + +1. Check the environment was setup correctly. + - **Option 1**: Run independent checks: + - For **Go development**: + 1. Execute: +``` +export GOLANG_PROTOBUF_REGISTRATION_CONFLICT=ignore +./gradlew :sdks:go:examples:wordCount +``` + - For **Python development**: + 1. Activate your environment: +``` +python3 -m venv ~/.virtualenvs/env +. ~/.virtualenvs/bin/activate +``` + 2. Execute: +``` +./gradlew :sdks:python:wordCount +``` + - For **Java development**: + 1. Execute: +``` +./gradlew :examples:java:wordCount +``` + - **Option 2**: validate the Go, Java, and Python environments: +``` +./gradlew :checkSetUp +``` + **Important**: Make sure you have activated Python development. Review comment: This tip should come before the command. You could say something like, 'Activate your python environment and then run:'. ########## File path: website/www/site/content/en/contribute/_index.md ########## @@ -151,15 +181,52 @@ script which is part of the Beam repo: ### Development Setup {#development-setup} -1. If you need help with git forking, cloning, branching, committing, pull requests, and squashing commits, see - [Git workflow tips](https://cwiki.apache.org/confluence/display/BEAM/Git+Tips) -1. Clone the git repository. You can download it anywhere you like, however for Go development we recommend putting it in your [`$GOPATH`](https://golang.org/doc/gopath_code#GOPATH) (`$HOME/go` by default on Unix systems). +1. Check [Git workflow tips](https://cwiki.apache.org/confluence/display/BEAM/Git+Tips) if you need help with git forking, cloning, branching, committing, pull requests, and squashing commits. +1. Clone the git repository. You can download it anywhere you like. $ mkdir -p ~/go/src/github.com/apache $ cd ~/go/src/github.com/apache $ git clone https://github.com/apache/beam $ cd beam + - For Go development: + We recommend putting it in your [`$GOPATH`](https://golang.org/doc/gopath_code#GOPATH) (`$HOME/go` by default on Unix systems). + 1. Clone the repo, and update your branch as normal + $ git clone https://github.com/apache/beam.git + $ cd beam + $ git remote add <GitHub_user> [email protected]:<GitHub_user>/beam.git + $ git fetch --all + 1. Get or Update all the Go SDK dependencies + $ go get -u ./... + +1. Check the environment was setup correctly. + - **Option 1**: Run independent checks: + - For **Go development**: + 1. Execute: +``` +export GOLANG_PROTOBUF_REGISTRATION_CONFLICT=ignore +./gradlew :sdks:go:examples:wordCount +``` + - For **Python development**: + 1. Activate your environment: +``` +python3 -m venv ~/.virtualenvs/env +. ~/.virtualenvs/bin/activate +``` + 2. Execute: +``` +./gradlew :sdks:python:wordCount +``` + - For **Java development**: + 1. Execute: +``` +./gradlew :examples:java:wordCount +``` + - **Option 2**: validate the Go, Java, and Python environments: Review comment: I think this should be the first option. -- 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. For queries about this service, please contact Infrastructure at: [email protected]
