Sample Contributing Guides

contributing.md

Contributors Guide

Interested in contributing? Awesome! Before you do though, please read our Code of Conduct. We take it very seriously, and expect that you will as well.

There are many ways you can contribute! ❤️

Bug Reports and Fixes :bug

• If you find a bug, please search for it in the Issues, and if it isn't already tracked, create a new issue. Fill out the "Bug Report" section of the issue template. Even if an Issue is closed, feel free to comment and add details, it will still be reviewed.
• Issues that have already been identified as a bug (note: able to reproduce) will be labelled bug.
• Issues that are related to the examples apps will be labelled area:examples.
• If you'd like to submit a fix for a bug, send a Pull Request and mention the Issue number.
• Include tests that isolate the bug and verifies that it was fixed.

New Features :bulb

• If you'd like to add new functionality to this project, describe the problem you want to solve in a new Issue.
• Issues that have been identified as a feature request will be labelled enhancement.
• Issues that are related to the examples apps will be labelled area:examples.
• If you'd like to implement the new feature, please wait for feedback from the project maintainers before spending too much time writing the code. In some cases, enhancements may not align well with the project objectives at the time.

Tests 🔍, Documentation 📚, Miscellaneous :sparkles

• If you'd like to improve the tests, you want to make the documentation clearer, you have an alternative implementation of something that may have advantages over the way its currently done, or you have any other change, we would be happy to hear about it!
• If its a trivial change, go ahead and send a Pull Request with the changes you have in mind.
• If not, open an Issue to discuss the idea first.

If you're new to our project and looking for some way to make your first contribution, look for Issues labelled good first contribution.

Requirements

For your contribution to be accepted:

• You must have signed the Contributor License Agreement (CLA).
• The test suite must be complete and pass.
• The changes must be approved by code review.
• Commits should be atomic and messages must be descriptive. Related issues should be mentioned by Issue number.

If the contribution doesn't meet the above criteria, you may fail our automated checks or a maintainer will discuss it with you. You can continue to improve a Pull Request by adding commits to the branch from which the PR was created.

Interested in knowing more about about pull requests at Slack?

Creating a Pull Request

1. 🍴 Fork the repository on GitHub.
2. 🏃 Clone/fetch your fork to your local development machine. It's a good idea to run the tests just to make sure everything is in order.
3. 🌿 Create a new branch and check it out.
4. 🔮 Make your changes and commit them locally. Magic happens here!
5. ⤴️ Push your new branch to your fork. (e.g. git push username fix-issue-16).
6. 📥 Open a Pull Request on github.com from your new branch on your fork to master in this repository.

Maintainers

There are more details about processes and workflow in the Maintainer's Guide.

maintainers_guide.md

Maintainers Guide

This document describes tools, tasks and workflow that one needs to be familiar with in order to effectively maintain this project. If you use this package within your own software as is but don't plan on modifying it, this guide is not for you.

Tools

All you need to work with this project is a supported version of Node.js (see slackapi/bolt package.json field "engines") and npm (which is distributed with Node.js).

Tasks

Updating

This package is a dependency for our guides and other example apps. There are many ways to configure a sample app. We prefer to keep a single version of app.js which should be consistent with the instructions and code blocks on the Bolt JS Getting Started guide. This reduces the possibility of drift ocurring between multiple versions.

When making changes to this repo, it's also important to keep all of our other guides and apps up-to-date.

When updating this package, please ensure the following are also updated:

• Guides found at slackapi/bolt-js/docs/
• Example apps at slackapi/bolt-js/examples/getting-started-*.

Testing

This package does not have unit tests but has implemented the command npm test.

Releasing

1. Create the commit for the release:

   • Bump the version number in adherence to Semantic Versioning in package.json.
   • Update any dependency versions
   • Confirm tests pass by running npm test
   • Commit with a message including the new version number. For example v2.2.0.
   • Tag the commit with the version number. For example git tag 2.2.0.

2. Merge into main repository

   • Create a pull request with the commit that was just made. Be certain to include the tag. For example: git push username main:rel-v1.0.8 && git push --tags username.
   • Once tests pass and a reviewer has approved, merge the pull request. You will also want to update your local main branch.
   • Push the new tag up to origin git push --tags origin.

3. Distribute the release

   • At the moment this package is not distributed on npm.
   • It is only downloaded or cloned from GitHub.

4. (Slack Internal) Communicate the release internally. Include a link to the GitHub Release.

5. Announce on community.slack.com in #slack-api

Workflow

Versioning and Tags

This project is versioned using Semantic Versioning, particularly in the npm flavor. Each release is tagged using git.

Fork

As a maintainer, the development you do will be almost entirely off of your forked version of this package. The exception to this rule pertains to multiple collaborators working on the same feature, which is detailed in the Branches section below.

Branches

main is where active development occurs.

When developing, branches should be created off of your fork and not directly off of this package. If working on a long-running feature and in collaboration with others, a corresponding branch of the same name is permitted. This makes collaboration on a single branch possible, as contributors working on the same feature cannot push commits to others' open Pull Requests.

After a major version increment, there also may be maintenance branches created specifically for supporting older major versions.

Issue Management

All issues are managed under https://github.com/slackapi/bolt-js/issues.

Use the label area:examples to organize issues related to this example app repository.

Everything else

When in doubt, find the other maintainers and ask.

pull_request_template.md

Summary

Describe the goal of this pull request. Mention any related issue numbers from slackapi/bolt-js/issues.

Requirements (place an x in each [ ])

• I've read and understood the Contributing Guidelines and have done my best effort to follow them.
• I've read and agree to the Code of Conduct.