PUBLISHING.md

How to Publish a Serverlesspresso extension

To submit a new extension, 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-coffee repository.

Initial Setup

Fork and Clone the serverlesspresso repo.

1. Fork the original serverlesspresso repo to create a copy of the repo in your own GitHub account: https://github.com/aws-samples/serverless-coffee

2. Clone your copy of the repo to download it locally: git clone https://github.com/{your-github-username}/serverless-coffee.git

3. Change into the new local directory: cd serverless-coffee

4. Add the original serverless-coffee repo as another remote repo called "upstream": git remote add upstream https://github.com/aws-samples/serverless-coffee

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

   The output should look like this:

   origin  https://github.com/{your-github-username}/serverless-coffee.git (fetch)
   origin  https://github.com/{your-github-username}/serverless-coffee.git (push)
   upstream        https://github.com/aws-samples/serverless-coffee (fetch)
   upstream        https://github.com/aws-samples/serverless-coffee (push)
   

Create Branch

Create a new local branch for each serverlesspresso extension 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: Cloudatch Dashboard

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 serverlesspresso extension or modify existing code.

1. If you are creating a new serverlesspresso extension, copy the folder named "_extension-model" to start with a template: cp -r _extension-model {new-folder-name}
2. If you are modifying existing code, make your code changes now.
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 serverlesspresso extension - lambda-aurora-serverless

   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 serverlesspresso extension.

   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 serverlesspresso extension.
   4. Be sure to provide your information in the "Author bio" section.
   5. Click "Submit new issue".
   6. Example issue: https://github.com/aws-samples/serverless-coffee/issues/57

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 serverlesspresso extension, 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 do not need to create the architecture diagram image that appears above each serverlesspresso extension on ServerlessLand.com. The team that manages the website is responsible for creating the image.

5. For Lambda functions, include test cases in both CLI and JSON with example data.

   Example CLI Lambda invoke with test event:

   aws lambda invoke --function-name YOUR_FUNCTION_NAME --invocation-type Event --payload '{"Key1": "Value1","Key2": "Value2"}' output.txt
   

   Example JSON Lambda test event:

   {
       "Key1": "Value1",
       "Key2": "Value2"
   }

Example Extensions

1. OrderRobotExtension: GitHub
2. Persist Order Metrics To DynamoDB: GitHub
3. Event Player: GitHub