Skip to content

Latest commit

 

History

History
96 lines (70 loc) · 5.74 KB

CONTRIBUTING.md

File metadata and controls

96 lines (70 loc) · 5.74 KB
Raw

Contributing to grammY

First of all, thanks for your interest in helping out! We appreciate any kind of support, be it small bug fixes, large feature contributions, or even just if you drop us a message with some constructive criticism how grammY can be improved for your use case. This library would not be possible without you.

We believe it is a strength of grammY to provide an integrated experience to its users. Important plugins have a dedicated page right inside the main documentation, and they are published under @grammyjs both on GitHub and on npm. If you have a good idea, don't hesitate to tell us in the group chat! We can grant you access to the GitHub Organization, so you can get a dedicated repository under our name, and publish your code as an offcial plugin of grammY. You will be responsible for maintaining it.

A Few Words on Deno and Node

TL;DR working on grammY means working on a Deno project, and that is a good thing.

grammY started out as a hybrid project, targeting both Deno and Node.js as runtimes not long after the Deno 1.0 release. In the beginning, this posed a challenge to grammY. There were no sufficiently good tools to convert a codebase back and forth between the ecosystems, so we had to maintain our own shell scripts to convert the Deno code to run under Node.js.

However, after some time the amazing tool deno2node emerged out of grammY's need. It solves this problem substantially better by providing a Deno-aware wrapper of the TypeScript compiler. Hence, you can write a Deno project and directly compile it to JavaScript files that run under Node.js.

In other words, working on grammY effectively means work on a Deno project. We use Deno testing, Deno linting, Deno formatting, and the Deno extension for VSCode. Your usual TypeScript tooling does not work—and once you tried developing for Deno and you have experienced how superior the development experience is, you will know why we are happy about our choice.

Note that not all plugins of grammY have to have the same setup: many of them only integrate with grammY itself, and hence can be written for Node and automatically ported to Deno via https://skypack.dev/ and similar services.

How to Contribute

There are several areas of contributions, and they have different ways to get you started.

  • Docs. You can always just edit the documentation by clicking the link at the bottom of the respective page. This will open a pull request on GitHub.
  • Core. We are happy to take pull requests of any kind against the core code base of grammY. If you're unsure whether or not your work goes in the right direction, simply ask about it in an issue or in the Telegram chat.
  • Plugins. There are both official plugins and third-party plugins. Our official plugins need to be of high quality (100 % TypeScript, ES6, Deno support, docs that are on par with grammY, semver, etc). Third-party plugins are independent and anyone can do them however they want. If a third-party plugin was to be listed on the website, some docs would be nice.
  • Storage adapters. Please send a message to the group chat if you want to create an offical storage adapter for the session plugin. You will be granted all necessary permissions, and the repository will be listed here. Consider checking out an existing implementation to make your life easier, e.g. this one.
  • Issues, bugs, and everything else. We're happy to hear from you if you want to report a bug, request a feature, or contribute anything else—also if it is not code. There are no technical steps to this.

Working on the Core of grammY using Deno (recommended)

If you just want to build from the newest version of the source code on GitHub, you can directly import from https://raw.githubusercontent.com/grammyjs/grammY/main/src/mod.ts. (Naturally, you can replace main by another branch name, e.g. in order to test a PR.)

If you want to read or modify grammY's code, you can do the following.

  1. Install Deno from https://deno.land.
  2. Use https://marketplace.visualstudio.com/items?itemName=denoland.vscode-deno or a similar extension if you are using a different editor.
  3. Clone this repo.
  4. Run deno cache src/mod.ts in the root directory of the repo.

You are now ready to work on grammY.

Before you open a PR, make sure to run deno test, deno fmt and deno lint on the Deno codebase. Specify --config deno.json for the latter two commands.

Working on the Core of grammY using Node.js

You can install grammY directly from source via

# main branch
npm install grammyjs/grammy
# another branch, e.g. called branch-name
npm install grammyjs/grammy#branch-name

which will download grammY and build the code locally.

If you want to read or modify grammY's code, you can do the following.

  1. Clone this repo.
  2. Install the dependencies via npm install. This will also compile the project for you.
  3. Use npm link to integrate grammY into your bot project.

Working on an Official Plugin of grammY

This works analogously to the grammY core development.

If you want to publish a new official plugin, a quick message in the group chat is enough and you will be granted the necessary permissions to work on a repository under the @grammyjs organisation on GitHub, and to publish your plugin on npm. You will be responsible for maintaining it, but perhaps other people will join in.