This is an automated email from the ASF dual-hosted git repository.
damccorm pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/beam.git
The following commit(s) were added to refs/heads/master by this push:
new 152626396c7 Colab Examples ReadMe Update (#27637)
152626396c7 is described below
commit 152626396c7a421093f9c8fb3b646a2e4776dd38
Author: Svetak Sundhar <[email protected]>
AuthorDate: Mon Jul 24 14:19:55 2023 -0400
Colab Examples ReadMe Update (#27637)
* Created using Colaboratory
* update documentation for ReadMe
* update documentation for ReadMe
* update documentation for ReadMe
* update documentation for ReadMe
* merge
* merge
* whitespace
* delete
---
examples/notebooks/README.md | 34 +++++++++++++++++++++++-----------
1 file changed, 23 insertions(+), 11 deletions(-)
diff --git a/examples/notebooks/README.md b/examples/notebooks/README.md
index 34505d28242..381e7d640c6 100644
--- a/examples/notebooks/README.md
+++ b/examples/notebooks/README.md
@@ -19,15 +19,18 @@
# Interactive Python Notebooks
-## Adding a notebooks
-1. Import an .ipynb file or create a new notebook on [Google
Colab](https://colab.research.google.com).
-1. In the upper-left corner menu, go to *File* -> *Save a copy in Github...*
+Thank you for choosing to contribute an example! This will help both the Beam
Developer community as well as the Beam User
+community.
+
+## Adding a notebook
+1. Import an .ipynb file or create a new notebook on [Google
Colab](https://colab.research.google.com).
+2. In the upper-left corner menu, go to *File* -> *Save a copy in Github...*
> You'll be asked to authenticate on GitHub.
-1. Select the *Repository* as `your-username/beam` and the *Branch* you're
working on, not master!
-1. Set the file path to somewhere inside `examples/notebooks/`, e.g.
`examples/notebooks/get-started/try-apache-beam-py.ipynb`.
+3. Select the *Repository* as `your-username/beam` and the *Branch* you're
working on, not master!
+4. Set the file path to somewhere inside `examples/notebooks/`, e.g.
`examples/notebooks/get-started/try-apache-beam-py.ipynb`.
> You can leave the commit message as the default value, we'll squash all
the commits into a single one at the end anyways.
-1. Make sure the *Include a link to Colaboratory* is checked.
-1. Pull the latest changes from the remote branch.
+5. Make sure the *Include a link to Colaboratory* is checked.
+6. Pull the latest changes from the remote branch.
```sh
git pull
```
@@ -36,12 +39,12 @@
git checkout -- file1 file2 .. fileN
git pull
```
-1. Repeat for all the notebooks you want to add.
-1. From the project root directory, patch the Notebooks to point to the
`master` branch instead of the local branch.
+7. Repeat for all the notebooks you want to add.
+8. From the project root directory, patch the Notebooks to point to the
`master` branch instead of the local branch.
```sh
python examples/notebooks/patch.py
```
-1. Squash all the commits into a single commit.
+9. Squash all the commits into a single commit.
```sh
git commit --all --amend
```
@@ -63,4 +66,13 @@
```
> NOTE: in vim you can do this with `:2,$s/^pick/s/g`
- Finally, your editor will open again. All the commit messages will be
visible, delete and reword as necessary to leave only one uncommented commit
message. After closing your editor all your commits should be squashed :)
\ No newline at end of file
+ Finally, your editor will open again. All the commit messages will be
visible, delete and reword as necessary to leave only one uncommented commit
message. After closing your editor all your commits should be squashed :)
+
+## Notebook Example Guidelines
+
+1. Use
[InteractiveRunner](https://cloud.google.com/dataflow/docs/guides/interactive-pipeline-development)
and [DirectRunner](https://beam.apache.org/documentation/runners/direct/) as
much as possible, to maintain Beam's vision of being runner-agnostic.
+2. If you must use another runner or external technologies, document all
commands and instructions needed for authentication, etc.
+3. Document steps to import external files onto Colab, if needed.
+4. Refrain from having too many code cells without explanation. Remember, this
code should be able to be understood by someone with none or very limited
experience in Beam!
+
+*Thanks again for choosing to contribute an example!*
