Skip to content

Latest commit

 

History

History
120 lines (78 loc) · 6.14 KB

PUBLISHING.md

File metadata and controls

120 lines (78 loc) · 6.14 KB
Raw

How to Publish a Step Functions Workflow on ServerlessLand

To submit a new workflow, or to make changes to existing code, follow the instructions below.

Repo Names

  • local: Your local copy of the forked repository.
  • origin: Your forked, remote copy of the original repository.
  • upstream: The original, remote serverless-patterns repository.

Initial Setup

Fork and Clone the workflows-collection repo.

  1. Fork the original workflows-collection repo to create a copy of the repo in your own GitHub account: https://github.com/aws-samples/step-functions-workflows-collection

  2. Clone your copy of the repo to download it locally: git clone https://github.com/{your-github-username}/step-functions-workflows-collection.git

  3. Change into the new local directory: cd step-functions-workflows-collection

  4. Add the original step-functions-workflows-collection repo as another remote repo called "upstream": git remote add upstream https://github.com/aws-samples/step-functions-workflows-collection

  5. For verification, display the remote repos: git remote -v

    The output should look like this:

    origin  https://github.com/{your-github-username}/step-functions-workflows-collection.git (fetch)
origin  https://github.com/{your-github-username}/step-functions-workflows-collection.git (push)
upstream        https://github.com/aws-samples/step-functions-workflows-collection (fetch)
upstream        https://github.com/aws-samples/step-functions-workflows-collection (push)

Create Branch

Create a new local branch for each workflow or modification being made. This allows you to create separate pull requests in the upstream repo.

  1. Create and checkout a new local branch before making code changes: git checkout -b {branch-name}

    Branch name syntax: {username}-{feature|fix}-{description}

    Example branch name: try-catch-workflow

  2. For verification, display all branches: git branch -a

    The output should look like this:

    * {branch-name}
main
remotes/origin/HEAD → origin/main
remotes/origin/main

Your Code

Now is the time to create your new workflow or modify existing code.

  1. If you are creating a new workflow, copy the folder named "_workflow_model" to start with a template: cp -r _workflow_model {new-folder-name}

  2. If you are modifying existing code, make your code changes now.

    Alternatively, if you have an existing GitHub repository with the associated template and workflow files you can use thisit to host your workflow instead.

  3. When your code is complete, stage the changes to your local branch: git add .

  4. Commit the changes to your local branch: git commit -m 'Comment here'

Pull Request

Push your code to the remote repos and create a pull request.

  1. Push the local branch to the remote origin repo: git push origin {branch-name}

    If this is the first push to the remote origin repo, you will be asked to Connect to GitHub to authorize the connection. Sometimes the pop-up window appears behind other windows.

  2. Go to the upstream repo in Github and click "Compare & pull request".

    1. Enter an appropriate title:

      Example title: New step-functions-workflows-collection - try-catch-workflow

    2. Add a description of the changes.

    3. Click "Create pull request".

  3. Submit a new issue to provide the additional details that will be used to build the Step Functions workflows collection web page on ServerlessLand.com.

    1. Provide responses to each section (eg: Description, Language, Framework, etc.)
    2. Add a link to the pull request in the "GitHub PR for template" section. If you type a hashtag (#), it will display a list of the current pull requests to select from.
    3. Consider adding a few links to AWS documentation in the "Additional resources" section to provide more information about your serverless pattern.
    4. Be sure to provide your information in the "Author bio" section.
    5. Click "Submit new issue".
    6. Example issue: aws-samples#3

Sync Repos

After your pull request has been accepted into the upstream repo:

  1. Switch to your local main branch: git checkout main
  2. Pull changes that occurred in the upstream repo: git fetch upstream
  3. Merge the upstream main branch with your local main branch: git merge upstream/main main
  4. Push changes from you local repo to the remote origin repo: git push origin main

Delete Branches

Delete any unnecessary local and origin branches.

  1. Switch to your local main branch: git checkout main
  2. For verification, display all branches: git branch -a
  3. Delete any unnecessary local branches: git branch -d {branch-name}
  4. Delete any unnecessary remote origin branches: git push origin --delete {branch-name}

Helpful Tips

  1. When creating a README file for your serverless pattern, place example code and commands within a code block.
  2. When deploying with SAM, use SAM policy templates for permissions whenever possible.
  3. Within your code and the SAM template, use comments liberally to help others understand what is going on.
  4. You must include an image of teh Step functions workflow exported from workflow studio.

Example workflows

  1. Wait for callback (hosted in this repo): Website | GitHub
  2. Query athena: Website | GitHub