From b3ae520644179a2165782a556fff727ff4b77f39 Mon Sep 17 00:00:00 2001 From: Samhita Alla Date: Wed, 29 Sep 2021 14:17:23 +0530 Subject: [PATCH] Update FlyteCTL Contribution Guide (#183) * Update FlyteCTL Contribution Guide Signed-off-by: Samhita Alla * delete CONTRIBUTE.md file Signed-off-by: Samhita Alla * fix contribute.rst Signed-off-by: Samhita Alla * fix readme Signed-off-by: Samhita Alla * fix readme Signed-off-by: Samhita Alla * update contrib guide Signed-off-by: Samhita Alla * update contrib guide Signed-off-by: Samhita Alla * update contrib guide Signed-off-by: Samhita Alla * update contrib guide Signed-off-by: Samhita Alla * update README Signed-off-by: Samhita Alla --- flytectl/.gitignore | 1 + flytectl/README.md | 80 ++++++++++++++++++----------- flytectl/docs/CONTRIBUTING.md | 25 --------- flytectl/docs/source/contribute.rst | 73 ++++++++++++++++++++++++++ flytectl/docs/source/index.rst | 2 +- 5 files changed, 124 insertions(+), 57 deletions(-) delete mode 100644 flytectl/docs/CONTRIBUTING.md create mode 100644 flytectl/docs/source/contribute.rst diff --git a/flytectl/.gitignore b/flytectl/.gitignore index c1b726f812..0cfb4d69b2 100644 --- a/flytectl/.gitignore +++ b/flytectl/.gitignore @@ -7,3 +7,4 @@ _test ./config.yaml docs/build/* cmd/upgrade/flyte.ext +.vscode diff --git a/flytectl/README.md b/flytectl/README.md index 1dab7131eb..45006d74c7 100644 --- a/flytectl/README.md +++ b/flytectl/README.md @@ -1,4 +1,19 @@ -# flytectl + +

+ Flyte Logo +

+

+ FlyteCTL +

+

+ The official Flyte command-line interface +

+

+ Documentation + Β· + Contribution Guide +

+ [![Docs](https://readthedocs.org/projects/flytectl/badge/?version=latest&style=plastic)](https://flytectl.rtfd.io) [![Current Release](https://img.shields.io/github/release/flyteorg/flytectl.svg)](https://github.com/flyteorg/flytectl/releases/latest) @@ -10,42 +25,45 @@ ![Commit activity](https://img.shields.io/github/commit-activity/w/lyft/flytectl.svg?style=plastic) ![Commit since last release](https://img.shields.io/github/commits-since/lyft/flytectl/latest.svg?style=plastic) -Flytectl is designed to be a portable, lightweight, CLI for working with Flyte. It is written in Golang and can access FlyteAdmin +FlyteCTL is designed to be a portable and lightweight CLI to work with Flyte. It is written in Golang and can access [FlyteAdmin](https://github.com/flyteorg/flyteadmin/)β€”the control plane of Flyte. -## Docs +## πŸš€ Quick Start -Docs are generated using Sphinx and are available at [flytectl.rtfd.io](https://flytectl.rtfd.io) -Generating docs locally can be accomplished by running make gendocs from within the docs folder +1. Install FlyteCTL with bash or shell script + * Bash + ```bash + $ brew install flyteorg/homebrew-tap/flytectl + ``` + * Shell script + ```bash + $ curl -s https://raw.githubusercontent.com/lyft/flytectl/master/install.sh | bash + ``` +2. (Optional) `flytectl upgrade` provides a general interface to upgrade FlyteCTL; run the command shown in the output -## Installation +3. Start sandbox using FlyteCTL + ```bash + $ flytectl sandbox start + ``` -Install flytectl with homebrew tap -```bash -$ brew install flyteorg/homebrew-tap/flytectl +4. Register examples + ```bash + # Register core workflows + $ flytectl register examples -d development -p flytesnacks + ``` -# Upgrade flytectl -$ brew upgrade flytectl -``` + +

+ πŸ“– How to Contribute to FlyteCTL +

+ -Install flytectl with shell script -```bash -$ curl -s https://raw.githubusercontent.com/lyft/flytectl/master/install.sh | bash -``` +You can find the detailed contribution guide [here](docs/source/contribute.rst). -## Get Started + +

+ 🐞 File an Issue +

+ -### Create a sandbox cluster -```bash -$ flytectl sandbox start -``` - -### Register flytesnacks example -```bash -# Run Core workflows -$ flytectl register examples -d development -p flytesnacks -``` - -## Contributing - -[Contribution guidelines for this project](docs/CONTRIBUTING.md) +Refer to the [issues](https://docs.flyte.org/en/latest/community/contribute.html#issues) section in the contribution guide if you'd like to file an issue. \ No newline at end of file diff --git a/flytectl/docs/CONTRIBUTING.md b/flytectl/docs/CONTRIBUTING.md deleted file mode 100644 index f170374b9e..0000000000 --- a/flytectl/docs/CONTRIBUTING.md +++ /dev/null @@ -1,25 +0,0 @@ -# Developing FlyteCtl - -A local cluster can be setup via --> https://docs.flyte.org/en/latest/getting_started.html - -Then, if having trouble connecting to local cluster see the following: - -#1) Find/Set/Verify gRPC port for your local Flyte service: - -FLYTECTL_GRPC_PORT=`kubectl get service -n flyte flyteadmin -o json | jq '.spec.ports[] | select(.name=="grpc").port'` - -#2) Setup Port forwarding: kubectl port-forward -n flyte service/flyteadmin 8081:$FLYTECTL_GRPC_PORT - -#3) Update config line in https://github.com/flyteorg/flytectl/blob/master/config.yaml to dns:///localhost:8081 - -#4) All new flags introduced for flytectl commands and subcommands should be camelcased. eg: bin/flytectl update project -p flytesnacks --activateProject - -# DCO: Sign your work - -Flyte ships commit hooks that allow you to auto-generate the DCO signoff line if -it doesn't exist when you run `git commit`. Simply navigate to the flytectl project root and run - -```bash -make setup-precommit -``` - diff --git a/flytectl/docs/source/contribute.rst b/flytectl/docs/source/contribute.rst new file mode 100644 index 0000000000..bbb5d385f6 --- /dev/null +++ b/flytectl/docs/source/contribute.rst @@ -0,0 +1,73 @@ +########################### +FlyteCTL Contribution Guide +########################### + +First off, thank you for thinking about contributing! +Below you’ll find instructions that will hopefully guide you through how to contribute to, fix, and improve FlyteCTL. + +πŸ“ Contribute to Documentation +============================== + +Docs are generated using Sphinx and are available at [flytectl.rtfd.io](https://flytectl.rtfd.io). + +To update the documentation, follow these steps: + +1. Install the requirements by running ``pip install -r doc-requirements.txt`` in the root folder +2. Make modifications in the `docs/source/gen `__ folder +3. Run ``make gendocs`` from within the `docs `__ folder +4. Open html files produced by Sphinx in your browser to verify if the changes look as expected (html files can be found in the ``docs/build/html`` folder) + +πŸ’» Contribute Code +================== + +1. Run ``make compile`` in the root directory to compile the code +2. Set up a local cluster by running ``./bin/flytectl sandbox start`` in the root directory +3. Run ``flytectl get project`` to see if things are working +4. Run the command you want to test in the terminal +5. If you want to update the command (add additional options, change existing options, etc.): + + * Navigate to `cmd `__ directory + * Each sub-directory points to a command, for example, ``create`` points to ``flytectl create ...`` + * Here are the directories you can navigate to: + + .. list-table:: FlyteCTL cmd directories + :widths: 25 25 50 + :header-rows: 1 + + * - Directory + - Command + - Description + * - ``config`` + - ``flytectl config ...`` + - Common package for all commands; has root flags + * - ``configuration`` + - ``flytectl configuration ...`` + - Command to validate/generate flytectl config + * - ``create`` + - ``flytectl create ...`` + - Command to create a project/execution + * - ``delete`` + - ``flytectl delete ...`` + - Command to abort an execution and delete resource attributes + * - ``get`` + - ``flytectl get ...`` + - Command to get a task/workflow/launchplan/execution/project/resource's-attributes + * - ``register`` + - ``flytectl register ...`` + - Command to register a task/workflow/launchplan + * - ``sandbox`` + - ``flytectl sandbox ...`` + - Command to interact with sandbox + * - ``update`` + - ``flytectl update ...`` + - Command to update a project/launchplan/resource's-attributes + * - ``upgrade`` + - ``flytectl upgrade ...`` + - Command to upgrade/rollback FlyteCTL version + * - ``version`` + - ``flytectl version ...`` + - Command to fetch FlyteCTL version + + Find all FlyteCTL commands on the `Nouns `__ page. + * Run appropriate tests to test the changes by running ``go test ./... -race -coverprofile=coverage.txt -covermode=atomic -v`` + in the root directory \ No newline at end of file diff --git a/flytectl/docs/source/index.rst b/flytectl/docs/source/index.rst index 3125fb7637..40a953745c 100644 --- a/flytectl/docs/source/index.rst +++ b/flytectl/docs/source/index.rst @@ -143,4 +143,4 @@ Flytectl configuration Install and Configure verbs nouns - Contribute + contribute