From a8b16a5d8fa405d237bfe1365debacfad673dc2a Mon Sep 17 00:00:00 2001 From: Nikki Everett Date: Mon, 14 Oct 2024 12:46:40 -0500 Subject: [PATCH] Update contributing docs (#5830) * apply changes from @cosmicBboy flytesnacks PR https://github.com/flyteorg/flytesnacks/pull/1736 to docs contributing guide, plus make additional changes Signed-off-by: nikki everett * move docs contributing guide to new subdirectory Signed-off-by: nikki everett * move contributing guides into separate docs Signed-off-by: nikki everett * small edits Signed-off-by: nikki everett * add formatting info to docs contributing doc Signed-off-by: nikki everett * small edit Signed-off-by: nikki everett * explain difference between user guide and tutorials and integrations python files in flytesnacks Signed-off-by: nikki everett * update redirects Signed-off-by: nikki everett * update links Signed-off-by: nikki everett --------- Signed-off-by: nikki everett --- .../contribute_code.rst} | 168 +---------------- docs/community/contribute/contribute_docs.md | 59 ++++++ .../contribute_examples.md} | 175 +++++++----------- docs/community/contribute/index.rst | 64 +++++++ docs/community/index.rst | 5 +- docs/conf.py | 3 +- .../flyte_agents/developing_agents.md | 2 +- docs/user_guide/index.md | 2 +- 8 files changed, 203 insertions(+), 275 deletions(-) rename docs/community/{contribute.rst => contribute/contribute_code.rst} (77%) create mode 100644 docs/community/contribute/contribute_docs.md rename docs/community/{contribute_docs.md => contribute/contribute_examples.md} (61%) create mode 100644 docs/community/contribute/index.rst diff --git a/docs/community/contribute.rst b/docs/community/contribute/contribute_code.rst similarity index 77% rename from docs/community/contribute.rst rename to docs/community/contribute/contribute_code.rst index ee84046369..c0cae7dade 100644 --- a/docs/community/contribute.rst +++ b/docs/community/contribute/contribute_code.rst @@ -1,136 +1,8 @@ -.. _contribute_Flyte: +################# +Contributing code +################# -##################### -Contributing to Flyte -##################### - -.. tags:: Contribute, Basic - -Thank you for taking the time to contribute to Flyte! -Please read our `Code of Conduct `__ before contributing to Flyte. - -Here are some guidelines for you to follow, which will make your first and follow-up contributions easier. - -TL;DR: Find the repo-specific contribution guidelines in the `Component Reference <#component-reference>`__ section. - -💻 Becoming a contributor -========================= - -An issue tagged with `good first issue `__ is the best place to start for first-time contributors. - -**Appetizer for every repo: Fork and clone the concerned repository. Create a new branch on your fork and make the required changes. Create a pull request once your work is ready for review.** - -.. note:: - To open a pull request, refer to `GitHub's guide `__ for detailed instructions. - -Example PR for your reference: `GitHub PR `__. -A couple of checks are introduced to help maintain the robustness of the project. - -#. To get through DCO, sign off on every commit (`Reference `__) -#. To improve code coverage, write unit tests to test your code -#. Make sure all the tests pass. If you face any issues, please let us know - -On a side note, format your Go code with ``golangci-lint`` followed by ``goimports`` (use ``make lint`` and ``make goimports``), and Python code with ``black`` and ``isort`` (use ``make fmt``). -If make targets are not available, you can manually format the code. -Refer to `Effective Go `__, `Black `__, and `Isort `__ for full coding standards. - -As you become more involved with the project, you may be able to be added as a contributor to the repos you're working on, -but there is a medium term effort to move all development to forks. - -📃 Documentation -================ - -Flyte uses Sphinx for documentation. ``protoc-gen-doc`` is used to generate the documentation from ``.proto`` files. - -Sphinx spans multiple repositories under `flyteorg `__. It uses reStructured Text (rst) files to store the documentation content. -For API- and code-related content, it extracts docstrings from the code files. - -To get started, refer to the `reStructuredText reference `__. - -For minor edits that don't require a local setup, you can edit the GitHub page in the documentation to propose improvements. - -Intersphinx -*********** - -`Intersphinx `__ can generate automatic links to the documentation of objects in other projects. - -To establish a reference to any other documentation from Flyte or within it, use Intersphinx. - -To do so, create an ``intersphinx_mapping`` in the ``conf.py`` file which should be present in the respective ``docs`` repository. -For example, ``rsts`` is the docs repository for the ``flyte`` repo. - -For example: - -.. code-block:: python - - intersphinx_mapping = { - "python": ("https://docs.python.org/3", None), - "flytekit": ("https://flyte.readthedocs.io/projects/flytekit/en/master/", None), - } - -The key refers to the name used to refer to the file (while referencing the documentation), and the URL denotes the precise location. - -Here is an example using ``:std:doc``: - -* Direct reference - - .. code-block:: text - - Task: :std:doc:`/api/flytekit/generated/flytekit.task` - - Output: - - Task: :std:doc:`/api/flytekit/generated/flytekit.task` - -* Custom name - - .. code-block:: text - - :std:doc:`Using custom words ` - - Output: - - :std:doc:`Using custom words ` - -| - -You can cross-reference multiple Python objects. Check out this `section `__ to learn more. - -| - -For instance, `task` decorator in flytekit uses the ``func`` role. - -.. code-block:: text - - Link to flytekit code :py:func:`flytekit:flytekit.task` - -Output: - -Link to flytekit code :py:func:`flytekit:flytekit.task` - -| - -Here are a couple more examples. - -.. code-block:: text - - :py:mod:`Module ` - :py:class:`Class ` - :py:data:`Data ` - :py:func:`Function ` - :py:meth:`Method ` - -Output: - -:py:mod:`Module ` - -:py:class:`Class ` - -:py:data:`Data ` - -:py:func:`Function ` - -:py:meth:`Method ` +.. _component_reference: 🧱 Component reference ====================== @@ -263,16 +135,6 @@ To build the Flyte docs locally you will need the following prerequisites: * - **Purpose**: Standard Library for Shared Components * - **Language**: Go -``flytesnacks`` -*************** - -.. list-table:: - - * - `Repo `__ - * - **Purpose**: Examples, Tips, and Tricks to use Flytekit SDKs - * - **Language**: Python (In the future, Java examples will be added) - * - **Guidelines**: Refer to the `Flytesnacks Contribution Guide `__ - ``flytectl`` ************ @@ -706,25 +568,3 @@ You can access this endpoint at: # replace with your specific task execution parameters http://localhost:30080/api/v1/task_executions/flytesnacks/development/fe92c0a8cbf684ad19a8/n0?limit=10000 - - - - - -🐞 File an issue -================ - -We use `GitHub Issues `__ for issue tracking. The following issue types are available for filing an issue: - -* `Plugin Request `__ -* `Bug Report `__ -* `Documentation Bug/Update Request `__ -* `Core Feature Request `__ -* `Flytectl Feature Request `__ -* `Housekeeping `__ -* `UI Feature Request `__ - -If none of the above fit your requirements, file a `blank `__ issue. -Also, add relevant labels to your issue. For example, if you are filing a Flytekit plugin request, add the ``flytekit`` label. - -For feedback at any point in the contribution process, feel free to reach out to us on `Slack `__. diff --git a/docs/community/contribute/contribute_docs.md b/docs/community/contribute/contribute_docs.md new file mode 100644 index 0000000000..3b5d996abf --- /dev/null +++ b/docs/community/contribute/contribute_docs.md @@ -0,0 +1,59 @@ +(contribute_docs)= + +# Contributing documentation + +```{eval-rst} +.. tags:: Contribute, Basic +``` + +Whether you're a novice or experienced software engineer, data scientist, or machine learning +practitioner, we welcome your contributions to the Flyte documentation! + +The Flyte documentation comprises the following types: + +* **{ref}`User guide ` documentation:** Conceptual and procedural documentation about using Flyte features to accomplish tasks. +* **{ref}`Tutorials `:** Longer, more advanced guides that use multiple Flyte features to solve real-world problems. Some tutorials may require extra setup, while others can only run on larger clusters. +* **{ref}`Integrations examples `:** These examples showcase how to use the Flyte plugins that integrate with the broader data and machine learning ecosystem. +* **{ref}`Deployment documentation `:** Guidance on deploying and configuring the Flyte backend. +* **{doc}`API documentation <../../api/index>`:** flytekit, flytectl, and flyteidl documentation. + +For minor edits that don't require a local setup, you can edit the page in GitHub page to propose improvements. + +## Contributing to user guide and deployment documentation + +To update user guide or deployment documentation, edit the corresponding files in the [flyte repository](https://github.com/flyteorg/flyte/tree/master/docs/user_guide). + +### Code in user guide documentation + +If you want to include tested, runnable example code in user guide documentation, you will need to add your code to the examples directory of the [flytesnacks repository](https://github.com/flyteorg/flytesnacks). Write your code in regular Python, with regular comments. You can use the `rli` ([remoteliteralinclude](https://github.com/wpilibsuite/sphinxext-remoteliteralinclude/blob/main/README.md)) directive to include snippets of code from your example Python file. + +```{important} +Unlike the comments in tutorials and integrations examples Python files, the comments in user guide Python files in flytesnacks **will not** be transformed into Markdown and processed into HTML for the docs site. All prose documentation for the user guide is contained in the Flyte repo, in the `docs/user_guide` directory. +``` + +## Contributing to API documentation + +* **flytekit:** See the [flytekit repository](https://github.com/flyteorg/flytekit). Documentation consists of content in submodule `__init__.py` files, `rst` files, and docstrings in classes and methods. +* **flytectl:** See the [flyte repository](https://github.com/flyteorg/flyte/tree/master/flytectl). Documentation consists of `rst` files in the `flytectl/docs` directory and comments in code files. +* **flyteidl:** See the [flyte repository](https://github.com/flyteorg/flyte/tree/master/flyteidl). `protoc-gen-doc` is used to generate this documentation from `.proto` files. + +## Contributing tutorials and integrations examples + +Follow the steps in {ref}`Contributing tutorials or integrations examples `. + +## Docs formatting + +Our documentation contains a mix of Markdown and reStructuredText. + +### Markdown + +User guide documentation and tutorials and integrations examples uses MyST Markdown. For more information, see the [MyST syntax documentation](https://mystmd.org/guide/syntax-overview). + +### reStructuredText + +Deployment and API docs mostly use reStructured Text. For more information, see the [reStructuredText documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). + +### Python objects + +You can cross-reference multiple Python modules, functions, classes, methods, and global data in documentations. For more information, see the [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects). + diff --git a/docs/community/contribute_docs.md b/docs/community/contribute/contribute_examples.md similarity index 61% rename from docs/community/contribute_docs.md rename to docs/community/contribute/contribute_examples.md index c54c442ca7..780150309a 100644 --- a/docs/community/contribute_docs.md +++ b/docs/community/contribute/contribute_examples.md @@ -1,52 +1,14 @@ -(contribute_docs)= - -# Contributing documentation - -```{eval-rst} -.. tags:: Contribute, Basic -``` - -Whether you're a novice or experienced software engineer, data scientist, or machine learning -practitioner, we welcome your contributions to the Flyte documentation! - -The Flyte documentation comprises the following types: - -* **{ref}`User guide ` documentation:** Conceptual and procedural documentation about using Flyte features to accomplish tasks. -* **API documentation:** - * {doc}`flytekit <../api/flytekit/docs_index>` - * {doc}`flytectl <../api/flytectl/docs_index>` - * {doc}`flyteidl <../api/flyteidl/docs_index>` -* **{ref}`Tutorials `:** Longer, more advanced guides that use multiple Flyte features to solve real-world problems. Some tutorials may require extra setup, while others can only run on larger clusters. -* **{ref}`Integrations examples `:** These examples showcase how to use the Flyte plugins that integrate with the broader data and machine learning ecosystem. -* **{ref}`Deployment documentation `:** Guidance on deploying and configuring the Flyte backend. - -## Contributing to user guide and deployment documentation - -To update user guide or deployment documentation, edit the corresponding files in the [flyte repository](https://github.com/flyteorg/flyte/tree/master/docs/user_guide). - -### Code in user guide documentation - -If you want to include tested, runnable example code in user guide documentation, follow the steps below to add your code to the [flytesnacks repository](https://github.com/flyteorg/flytesnacks). Write your code in regular Python, with regular comments. These comments **will not** be extracted from the Python file and turned into user-facing documentation. You can use the `rli` ([remoteliteralinclude](https://github.com/wpilibsuite/sphinxext-remoteliteralinclude/blob/main/README.md)) directive to include snippets of code from your example Python file. - -## Contributing to API documentation - -* **flytekit:** See the [flytekit repository](https://github.com/flyteorg/flytekit). Documentation consists of content in submodule `__init__.py` files, `rst` files, and docstrings in classes and methods. -* **flytectl:** See the [flyte repository](https://github.com/flyteorg/flyte/tree/master/flytectl). Documentation consists of `rst` files in the `flytectl/docs` directory and comments in code files. -* **flyteidl:** See the [flyte repository](https://github.com/flyteorg/flyte/tree/master/flyteidl). - -## Contributing tutorials and integrations examples +(contribute_examples)= +# Contribute tutorials or integrations examples The first step to contributing a tutorial or integration example is to open a [documentation issue](https://github.com/flyteorg/flyte/issues/new?assignees=&labels=documentation%2Cuntriaged&template=docs_issue.yaml&title=%5BDocs%5D+) to describe the example you want to write. The Flyte maintainers will help you figure out where your tutorial or integration example would best fit. -### Creating a tutorial or integration example - :::{admonition} Prerequisites Follow the {ref}`env_setup` guide to get your development environment ready. ::: -The `flytesnacks` repo examples live in the `examples` directory, where each -subdirectory contains a self-contained example project that covers a particular tutorial or integration. There are also subdirectories that contain the code included in the user guide via the `rli` (remoteliteralinclude) directive. +The tutorials and integrations examples live in the `examples` directory of the [flytesnacks repo](https://github.com/flyteorg/flytesnacks), where each subdirectory contains a self-contained example project that covers a particular tutorial or integration. There are also subdirectories that contain the code included in the user guide via the `rli` (remoteliteralinclude) directive. ```{code-block} bash examples @@ -59,7 +21,7 @@ examples ... ``` -#### Adding an example script to an existing project +## Adding an example script to an existing project If you're adding a new example to an existing project, you can simply create a new `.py` file in the appropriate directory. For example, if you want to add a new @@ -81,7 +43,7 @@ my_new_example If you are creating a new user guide example, you can reference the code in the user guide documentation using the `rli` (remoteliteralinclude) directive. You do not need to add the new example to the `README.md` file of the example project. -#### Creating a new example project +## Creating a new example project ````{important} If you're creating a new tutorial or integration example @@ -91,7 +53,7 @@ new example project. In the `flytesnacks` root directory, run the following command to create an example project: ```{prompt} bash -./scripts/create-example-project new_example_project +./scripts/create-example-project.sh new_example_project ``` This will create a new directory under `examples`: @@ -103,15 +65,14 @@ examples/new_example_project ├── new_example_project │   ├── __init__.py │   └── example.py -├── requirements.in -└── requirements.txt +└── requirements.in ``` ```` -#### Creating Python examples +## Creating Python examples -##### Tutorial or integration examples +### Tutorial or integration examples If you are writing a tutorial or integration example, write your example Python script in [percent format](https://jupytext.readthedocs.io/en/latest/formats.html#the-percent-format), which allows you to interleave Python code and Markdown in the same file. Each @@ -137,7 +98,7 @@ giving you the utilities of Sphinx. `flytesnacks` uses the [jupytext](https://github.com/mwouts/jupytext) packages to interpret the Python files as rst-compatible files. -#### Writing examples: explain what the code does +## Writing examples: explain what the code does Following the [literate programming](https://en.wikipedia.org/wiki/Literate_programming) paradigm, make sure to interleave explanations in the `*.py` files containing the code example. @@ -158,7 +119,7 @@ argument. Can you think of a better name for this `function`? Explanations don't have to be this detailed for such a simple example, but you can imagine how this makes for a better reading experience for more complicated examples. -#### Creating examples in other formats +## Creating examples in other formats Writing examples in `.py` files is preferred since they are easily tested and packaged, but `flytesnacks` also supports examples written in `.ipynb` and @@ -170,9 +131,11 @@ packaged, but `flytesnacks` also supports examples written in `.ipynb` and - `.md`: When a piece of documentation doesn't require testable or packaged flyte tasks/workflows, an example page can be written as a MyST Markdown file. -**Note:** If you want to add Markdown files to a user guide example project, add them to the [flyte repository](https://github.com/flyteorg/flyte/tree/master/docs/user_guide) instead. +```{note} +If you want to add Markdown files to a user guide example project, add them to the [flyte repository](https://github.com/flyteorg/flyte/tree/master/docs/user_guide) instead. +``` -### Writing a README +## Writing a README The `README.md` file needs to capture the _what_, _why_, and _how_ of the example. @@ -199,13 +162,17 @@ be the names of the `.ipynb` or `.md` files (but without the file extension). Refer to any subdirectory in the `examples` directory ::: -### Test your code +## Test your code + +If the example code can be run locally, you can use `pyflyte run` to test it: -If the example code can be run locally, just use `python .py` to run it. +```{prompt} bash +pyflyte run .py -- -- ... +``` -#### Testing on a cluster +### Testing on a cluster -Install {doc}`flytectl `, the commandline interface for flyte. +Install {doc}`flytectl `, the command line interface for flyte. :::{note} Learn more about installation and configuration of Flytectl [here](https://docs.flyte.org/en/latest/flytectl/docs_index.html). @@ -219,39 +186,34 @@ flytectl demo start #### Testing the `basics` project examples on a local demo cluster -In this example, we'll build the `basics` project: +In this example, we'll build the `basics` project. + +Change to the basics directory: ```{prompt} bash # from flytesnacks root directory cd examples/basics ``` -Build the container: +Build and push the container to the local Docker registry provided by the demo cluster: ```{prompt} bash -docker build . --tag "basics:v1" -f Dockerfile +docker build . --tag "localhost:30000/basics:v1" -f Dockerfile --push ``` -Package the examples by running: +Run a workflow in the local demo cluster by specifying the `--image` flag +and passing the `--remote` flag: ```{prompt} bash -pyflyte --pkgs basics package --image basics:v1 -f -``` - -Register the examples by running - -```{prompt} bash -flytectl register files \ - -p flytesnacks \ - -d development \ - --archive flyte-package.tgz \ - --version v1 +pyflyte run --remote \ + --image localhost:30000/basics:v1 \ + basics/hello_world.py hello_world_wf ``` Visit `https://localhost:30081/console` to view the Flyte console, which consists of the examples present in the `flytesnacks/core` directory. -#### Updating dependencies +## Updating dependencies :::{admonition} Prerequisites Install [pip-tools](https://pypi.org/project/pip-tools/) in your development @@ -263,32 +225,33 @@ pip install pip-tools ::: -If you've updated the dependencies of the project, update the `requirements.txt` -file by running: +If the project uses pinned dependencies in a `requirements.in` file, run the `pip-compile` command to create a new pinned `requirements.txt` file: ```{prompt} bash pip-compile requirements.in --upgrade --verbose --resolver=backtracking ``` -#### Rebuild the image +## Rebuild the image -If you've updated the source code or dependencies of the project, and rebuild +If you've updated the source code or dependencies of the project, rebuild the image with: ```{prompt} bash -docker build . --tag "basics:v2" -f core/Dockerfile -pyflyte --pkgs basics package --image basics:v2 -f -flytectl register files \ - -p flytesnacks \ - -d development \ - --archive flyte-package.tgz \ - --version v2 +docker build . --tag "localhost:30000/basics:v2" -f Dockerfile --push +``` + +Next, run the workflow again with the new image: + +```{prompt} bash +pyflyte run --remote \ + --image localhost:30000/basics:v2 \ + basics/hello_world.py hello_world_wf ``` Refer to {ref}`this guide ` -if the code in itself is updated and requirements.txt is the same. +if the code itself is updated and requirements.txt is the same. -### Pre-commit hooks +## Pre-commit hooks We use [pre-commit](https://pre-commit.com/) to automate linting and code formatting on every commit. Configured hooks include [ruff](https://github.com/astral-sh/ruff) to ensure newlines are added to the end of files, and there is proper spacing in files. @@ -297,7 +260,7 @@ We run all those hooks in CI, but if you want to run them locally on every commi installing the dev environment requirements. In case you want to disable `pre-commit` hooks locally, run `pre-commit uninstall`. More info [here](https://pre-commit.com/). -#### Formatting +### Formatting We use [ruff](https://github.com/astral-sh/ruff) to autoformat code. They are configured as git hooks in `pre-commit`. Run `make fmt` to format your code. @@ -307,37 +270,41 @@ are configured as git hooks in `pre-commit`. Run `make fmt` to format your code. We use [codespell](https://github.com/codespell-project/codespell) to catch common misspellings. Run `make spellcheck` to spell-check the changes. -### Update documentation pages +## Update tutorials and integrations examples documentation pages -The `docs/conf.py` contains the Sphinx configuration for building the -`flytesnacks` documentation. +The `docs/conf.py` file in the flytesnacks repository contains the Sphinx configuration for building the `flytesnacks` documentation. At build time, the `flytesnacks` Sphinx build system will convert the tutorials and integrations examples in the `examples` directory into `docs/auto_examples` and make them available in the documentation. ::::{important} -The docs build system will convert the `README.md` files in each tutorials and example integration project -project into a `index.md` file, so you can reference the root page of each -example project, e.g., in MyST Markdown format, you can write a table-of-contents -directive like so: +The docs build system will convert the `README.md` files in each tutorial and example integration project into an `index.md` file, allowing you to reference the root page of each +example project in MyST Markdown format. + +:::: + +If you've created a new tutorial or integration example project, you'll need to add its `index` page +to the table of contents in `docs/tutorials/index.md` or `docs/integrations/index.md` and update the appropriate `list-table` directive in the file to make sure the example shows up in the documentation: :::{code-block} +```{list-table} +:header-rows: 0 +:widths: 20 30 + +* - {doc}`Airflow agent ` + - Run Airflow jobs in your workflows with the Airflow agent. + ... +``` + +... + ```{toc} /auto_examples/bigquery_agent/index ``` ::: -:::: - -If you've created a new tutorial or integration example project, you'll need to add its `index` page -to the table of contents in `docs/index.md` to make sure the project -shows up in the documentation. Additionally, you'll need to update the appropriate -`list-table` directive in `docs/tutorials/index.md`, or -`docs/integrations/index.md` so that it shows up in the respective section of the -documentation. - ### Build the documentation locally Verify that the code and documentation look as expected: @@ -355,10 +322,8 @@ Verify that the code and documentation look as expected: ### Create a pull request -Create the pull request in the flytesnacks repository, then ensure that the docs are rendered correctly by clicking on the documentation check. +Create the pull request in the flytesnacks repository, then ensure that the docs are rendered correctly by clicking on the documentation check: ```{image} https://github.com/user-attachments/assets/581330cc-c9ab-418d-a9ae-bb3c346603ba :alt: Docs link in a PR ``` - -You can refer to [this PR](https://github.com/flyteorg/flytesnacks/pull/332) for the exact changes required. \ No newline at end of file diff --git a/docs/community/contribute/index.rst b/docs/community/contribute/index.rst new file mode 100644 index 0000000000..eb13f5d73f --- /dev/null +++ b/docs/community/contribute/index.rst @@ -0,0 +1,64 @@ +.. _contribute_Flyte: + +##################### +Contributing to Flyte +##################### + +.. tags:: Contribute, Basic + +Thank you for taking the time to contribute to Flyte! +Please read our `Code of Conduct `__ before contributing to Flyte. + +Here are some guidelines for you to follow, which will make your first and follow-up contributions easier. + +TL;DR: Find the repo-specific contribution guidelines in the :ref:`Component Reference ` section. + +💻 Becoming a contributor +========================= + +An issue tagged with `good first issue `__ is the best place to start for first-time contributors. + +**Appetizer for every repo: Fork and clone the concerned repository. Create a new branch on your fork and make the required changes. Create a pull request once your work is ready for review.** + +.. note:: + To open a pull request, refer to `GitHub's guide `__ for detailed instructions. + +Example PR for your reference: `GitHub PR `__. +A couple of checks are introduced to help maintain the robustness of the project. + +#. To get through DCO, sign off on every commit (`Reference `__) +#. To improve code coverage, write unit tests to test your code +#. Make sure all the tests pass. If you face any issues, please let us know + +On a side note, format your Go code with ``golangci-lint`` followed by ``goimports`` (use ``make lint`` and ``make goimports``), and Python code with ``black`` and ``isort`` (use ``make fmt``). +If make targets are not available, you can manually format the code. +Refer to `Effective Go `__, `Black `__, and `Isort `__ for full coding standards. + +As you become more involved with the project, you may be able to be added as a contributor to the repos you're working on, +but there is a medium term effort to move all development to forks. + +🐞 File an issue +================ + +We use `GitHub Issues `__ for issue tracking. The following issue types are available for filing an issue: + +* `Plugin Request `__ +* `Bug Report `__ +* `Documentation Bug/Update Request `__ +* `Core Feature Request `__ +* `Flytectl Feature Request `__ +* `Housekeeping `__ +* `UI Feature Request `__ + +If none of the above fit your requirements, file a `blank `__ issue. +Also, add relevant labels to your issue. For example, if you are filing a Flytekit plugin request, add the ``flytekit`` label. + +For feedback at any point in the contribution process, feel free to reach out to us on `Slack `__. + +.. toctree:: + :maxdepth: 1 + :hidden: + + Contributing code + Contributing docs + Contributing tutorials or integrations examples \ No newline at end of file diff --git a/docs/community/index.rst b/docs/community/index.rst index dc95f5c0e7..2e1e740c98 100644 --- a/docs/community/index.rst +++ b/docs/community/index.rst @@ -30,7 +30,7 @@ Please join us on: Open Source Community Meeting ----------------------------- -When: every other Tuesday, 9:00 AM Pacific Time. +When: Every other Thursday, 11:00 AM Pacific Time. You're welcome to join and learn from other community members sharing their experiences with Flyte or any other technology from the AI ecosystem. Check out the event details and add it to your `calendar `_, or just pop in! @@ -106,8 +106,7 @@ Messages that don't follow these rules will be deleted. :maxdepth: 1 :hidden: - Contributing to Flyte - Contributing documentation + Contributing to Flyte Roadmap Frequently asked questions Troubleshooting guide diff --git a/docs/conf.py b/docs/conf.py index 9a8bbcaf0d..316acc60be 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -157,7 +157,8 @@ "flyte_fundamentals/visualizing_task_input_and_output": "../user_guide/flyte_fundamentals/visualizing_task_input_and_output.html", # flytesnacks - "flytesnacks/contribute": "../community/contribute_docs.html", + "flytesnacks/contribute": "../community/contribute/contribute_docs.html", + "community/contribute": "community/contribute/contribute_code.html", "flytesnacks/integrations": "../flytesnacks/integrations/index.html", "flytesnacks/tutorials": "../flytesnacks/tutorials.html", diff --git a/docs/user_guide/flyte_agents/developing_agents.md b/docs/user_guide/flyte_agents/developing_agents.md index ea0d082c05..f76c662fa0 100644 --- a/docs/user_guide/flyte_agents/developing_agents.md +++ b/docs/user_guide/flyte_agents/developing_agents.md @@ -15,7 +15,7 @@ If you need to create a new type of task, we recommend creating a new agent to r ```{note} -We strongly encourage you to contribute your agent to the Flyte community. To do so, follow the steps in "[Contributing to Flyte](https://docs.flyte.org/en/latest/community/contribute.html)" to add your agent to [Flytekit](https://github.com/flyteorg/flytekit/tree/master/plugins) and [create an example](https://docs.flyte.org/en/latest/flytesnacks/contribute.html) of your agent for the [Integrations](https://docs.flyte.org/en/latest/flytesnacks/integrations.html) documentation. If you have any questions, reach out to us on [Slack](https://docs.flyte.org/en/latest/community/contribute.html#). +We strongly encourage you to contribute your agent to the Flyte community. To do so, follow the steps in the [Flytekit contribution guide](https://docs.flyte.org/en/latest/api/flytekit/contributing.html) to add your agent to [Flytekit](https://github.com/flyteorg/flytekit/tree/master/plugins) and [create an example](https://docs.flyte.org/en/latest/flytesnacks/contribute.html) of your agent for the [Integrations](https://docs.flyte.org/en/latest/flytesnacks/integrations/index.html) documentation. If you have any questions, reach out to us on [Slack](https://docs.flyte.org/en/latest/community/contribute.html#). ``` diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index ae439c8760..5fd92c86c4 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -26,7 +26,7 @@ To learn about how to spin up and manage a Flyte cluster in the cloud, see the ``` ```{note} -Want to contribute or update an example? Check out the {doc}`Contribution Guide <../community/contribute_docs>`. +Want to contribute or update an example? Check out the {ref}`Contribution Guide `. ``` ## Table of contents