Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
If you have suggestions for how this project could be improved, or want to report a bug, open an issue! We'd love all and any contributions. If you have questions, too, we'd love to hear them.
We'd also love PRs. If you're thinking of a large PR, we advise opening up an issue first to talk about it, though! Look at the links below if you're not sure how to open a PR.
Setting up the bot is as easy as navigating to your project folder in the terminal and running;
source <(curl -s https://raw.githubusercontent.com/badging/bot-scripts/main/install.sh)If you are using an operating system not currently supported by the bot script, follow this tutorial:
- Node & NPM
- A GitHub account
- A smee.io webhook URL (to get this, head over to the website and click on 'Start a new channel'. A unique webhook url will be displayed. Save this for later).
Fork this repository by clicking on the fork button on the top of this page. This will create a copy of this repository in your account.
Fork the event-diversity-and-inclusion repository by clicking on the fork button on the repository page. This is where the GitHub app will be installed to test the bot.
Clone the forked repository to your machine by opening the forked repository, click on the 'code' button and then click the copy to clipboard icon.
Open a terminal on your local computer and run the following git command:
git clone "url you just copied"
Change to the repository directory on your computer (if you are not already there):
cd badging-bot
Now create a branch using the git switch command:
git switch -c your-new-branch-name
For example:
git switch -c add-my-bot-contributions
Create a .env file following the example_env file provided in the folder. This will be used to store all the credentials needed for the bot to run.
To generate your own credentials, you need to create your own GitHub App and configure it to run on the event-diversity-and-inclusion repository. To do this, follow this steps:
-
Head over to your Github account.
-
Go to 'Settings'.
- Scroll down and click on 'Developer Settings'
- Then, click on 'New GitHub App'.
This will take you to the page where you carry out authentication. Afterwards,, you will be taken to the setup page for the GitHub App where you imput some details.
-
Enter your desired name for the app.
-
For the homepage url, input the url displayed when you started a new Smee channel on SMee.io.
-
Do the same for the webhook url.
-
Input your desired string combination as webhook secret.
-
Under 'Permissions', click on the drop down arrow for 'Repository permissions'. Grant read and write access to environments, issues, pages and webhooks.
- Under 'Subscribe to events', check 'Issues' and 'issue-comments'.
- Under where can the GitHub App be installed', select 'Only on ths account'.
-
Then click on 'Create Github App'. You will be redirected to the page displaying your app's settings where you can fetch your credentials---AppId, ClientId, and Client secret and private key.
-
To access the private key, scroll down the page and click on the 'Generate private key' button to download a private key file (usually in the PEM format). Save this file in a secure location, as it will be required for authenticating and interacting with your GitHub app.
- At the top left section of the page, click on the 'Install App' button. You will be redirected to this page.
- Check 'Only select repositories'.
-
Search and select the diversity-and-inclusion-event repository that you forked earlier.
-
Click on Install.
Now you will be able to test and use the app's functionalities on the DEI badging for events repository.
- Head over to your .env file and input all the credentials generated. It should look like this:
appId=xxxxx
privateKey=xxxxx
clientId=xxxxx
clientSecret=xxxxx
webhookSecret=xxxxx
PORT=xxxxx
smee_URL=xxxxx- If you are using Windows OS, the start command for the project uses
NODE_ENVto set the environment for running the project to either ‘development’ or ‘production’, so you might get the error below error if you run the project.
NODE_ENV is not recognized as an internal or external command, operable command or batch file.To fix this, run the command below in a new terminal to install a node-env CLI globally on your machine:
npm install -g win-node-env- Start the app on the development envrionment using the command below:
npm run devThis will start the app on the development environment and connect to smee.io webhook URL.
- To test, head over to the event-diversity-and-inclusion repository and create a new issue. You will see that the bot has added a comment to the issue. When the issue is assigned to anyone,the bot will send the checklist for the event and so on.
- You can also see the webhook events on the smee.io page using the URL provided in the .env file.
-
To start adding more functionalities or improving existing ones, the core functions are written in the src directory. You can see few examples like
assignChecklist.js,welcome.js,issueComment.js,checkModerator.jsetc where the bot comands and logic are written. -
To add a new functionality/feature you created to the flow such that either a command or a condition met triggers the feature, you will extend the function in the
githubBot.jsfile. There you can state the condition or event that triggers any feature and the function that will be triggered.
Here are a few things you can do that will increase the likelihood of your pull request being accepted:
- Follow the style guide which is using standard. Any linting errors should be shown when running
npm test. - Write and update tests.
- Keep your changes as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
- Write a good commit message.
Work in Progress pull requests are also welcome to get feedback early on, or if there is something blocked you.