Skip to content

Latest commit

 

History

History
53 lines (36 loc) · 4.43 KB

CONTRIBUTING.md

File metadata and controls

53 lines (36 loc) · 4.43 KB

Contributing to examples folder

Thank you for your interest in contributing to the examples folder. This folder contains a collection of Python notebooks and selected markdown files that demonstrate various usage of this promptflow project. The script will automatically generate a README.md file in the root folder, listing all the notebooks and markdown files with their corresponding workflows.

Guidelines for notebooks and markdown files in examples folder

When creating or modifying a notebook or markdown file, please follow these guidelines:

  • Each notebook or markdown file should have a clear and descriptive title as the first line
  • Each notebook or markdown file should have a brief introduction that explains the purpose and scope of the example. For details, please refer to the readme workflow generator manual README.md file.
    • The first sentence of first paragraph of the markdown file is important. The introduction should be concise and informative, and end with a period.
    • Each notebook file should have a metadata area when the file is opened as a big JSON file. The metadata area may contain the following fields:
      • .metadata.description: (Mandatory) A short description of the example that will be displayed in the README.md file. The description should be concise and informative, and end with a period.
      • .metadata.stage: (Optional) A value that indicates whether the script should skip generating a workflow for this notebook or markdown file. If set to development, the script will ignore this file. If set to other values or omitted, the script will generate a workflow for this file.
  • Each notebook or markdown file should have a clear and logical structure, using appropriate headings, subheadings, comments, and code cells. The code cells should be executable and produce meaningful outputs.
  • Each notebook or markdown file should follow the PEP 8 style guide for Python code, and use consistent and readable variable names, indentation, spacing, and punctuation.
  • Each notebook or markdown file should include relevant references, citations, and acknowledgements.
  • If you are contributing to tutorial, each notebook or markdown file should declare its dependent resources in its metadata, so that the auto generated workflow can listen to the changes of these resources to avoid unexpected breaking. Resources should be declared with relative path to the repo root, and here are examples for notebook and markdown.

Generate workflows, update README.md and submit pull requests

To run the readme.py script, you need to have Python 3 installed on your system. You also need to install the required packages by running:

# At this examples folder
pip install -r requirements.txt
pip install -r dev_requirements.txt

Then, you can run the script by:

# At the root of this repository
python scripts/readme/readme.py

For detailed usage of readme.py, please refer to the readme workflow generator manual README.md

Update README.md in examples folder

The readme.py script will scan all the notebooks and markdown files in the examples folder, and generate a README.md file in the root folder. The README.md file will contain a table of contents with links to each notebook and markdown file, as well as their descriptions and workflows.

Generations in the workflows folder

This contains two parts:

  • For notebooks, we'll prepare standard workflow running environment to test the notebook to the end.
  • For markdowns, The workflows are generated by extracting the bash cells from markdown file. The workflows will prepare standard workflow running environment and test these cells to the end.

The script will also save workflows in the workflows folder, where each notebook or markdown file will have a corresponding workflow file with the .yml extension. The workflow files can be triggered by creating a new pull request or pushing a new commit to the repository. The workflow will run the notebook or markdown file, and you could check the outputs afterwards.

Feedback and Support

If you have any feedback or need any support regarding this folder, submit an issue on GitHub. We appreciate your contribution and hope you enjoy using our project.