Skip to content
This repository has been archived by the owner on Feb 18, 2024. It is now read-only.

Commit

Permalink
Merge pull request #59 from adeyinkaoresanya/adeyinka-tutorial-contri…
Browse files Browse the repository at this point in the history
…butions

[FEATURE] Create a tutorial for setting up the badging bot on local development environment
  • Loading branch information
kaxada authored Oct 11, 2023
2 parents e68a3df + 37c014b commit d5979fc
Show file tree
Hide file tree
Showing 21 changed files with 325 additions and 6 deletions.
Binary file added Assets/Adjust permissions.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Assets/Top Left Install App.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Assets/app details.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Assets/create github app button.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Assets/developer settings.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Assets/display github app settings.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Assets/event-example.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Assets/fork_DEI_badging_repo.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Assets/fork_badging_bot_repo.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Assets/generate private key.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Assets/github_profile settings.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Assets/install github app.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Assets/new github app button.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Assets/only select repositories.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Assets/run-badging-bot.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Assets/smee-page.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Assets/subscribe to events.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
158 changes: 156 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,166 @@ If you have suggestions for how this project could be improved, or want to repor

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 local development environment
## Setting up local development environment

Seeting up the bot is as easy as navigating to your project folder in the terminal and running;
Setting up the bot is as easy as navigating to your project folder in the terminal and running;

```sh
source <(curl -s https://raw.githubusercontent.com/badging/bot-scripts/main/install.sh)
```

</br>
</br>

If you are using an operating system not currently supported by the bot script, follow this tutorial:

### Tools needed

- Node & NPM
- A GitHub account
- A [smee.io](https://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).

### Steps

#### 1. Fork the Badging Bot repository
<img align="right" width="300" src="Assets/fork_badging_bot_repo.PNG" alt="fork the Badging Bot repository" />

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.

#### 2. Fork the Event Diversity and Inclusion repository

<img align="right" width="300" src="Assets/fork_DEI_badging_repo.PNG" alt="fork the Badging Bot repository" />

Fork the event-diversity-and-inclusion [repository](https://github.com/badging/event-diversity-and-inclusion) by clicking on the fork button on the repository page. This is where the GitHub app will be installed to test the bot.

#### 3. Clone the Badging Bot repository
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"
```

### Create a branch

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

### Generate credentials
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:

1. Head over to your Github account.

2. Go to 'Settings'.
<img width="300" src="Assets/github_profile settings.png" alt="fork the Badging Bot repository" />

3. Scroll down and click on 'Developer Settings'
<img width="300" src="Assets/developer settings.png" alt="fork the Badging Bot repository" />

4. Then, click on 'New GitHub App'.

<img width="300" src="Assets/new github app button.png" alt="fork the Badging Bot repository" />

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.

6. Enter your desired name for the app.

7. For the homepage url, input the url displayed when you started a new Smee channel on SMee.io.

<img width="300" src="Assets/app details.PNG" alt="fork the Badging Bot repository" />


8. Do the same for the webhook url.

9. Input your desired string combination as webhook secret.

10. Under 'Permissions', click on the drop down arrow for 'Repository permissions'. Grant read and write access to environments, issues, pages and webhooks.
<img width="300" src="Assets/Adjust permissions.png" alt="fork the Badging Bot repository" />

11. Under 'Subscribe to events', check 'Issues' and 'issue-comments'.
<img width="300" src="Assets/subscribe to events.png" alt="fork the Badging Bot repository" />

12. Under where can the GitHub App be installed', select 'Only on ths account'.
<img width="300" src="Assets/create github app button.png" alt="fork the Badging Bot repository" />

13. 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.

14. 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.
<img width="300" src="Assets/generate private key.png" alt="fork the Badging Bot repository" />

15. At the top left section of the page, click on the 'Install App' button. You will be redirected to this page.
<img width="300" src="Assets/Top Left Install App.png" alt="Top Left Install App" />

16. Check 'Only select repositories'.
<img width="300" src="Assets/only select repositories.png" alt="only select repositories" />

17. Search and select the diversity-and-inclusion-event repository that you forked earlier.

18. Click on Install.
<img width="300" src="Assets/install github app.png" alt="install github app" />

Now you will be able to test and use the app's functionalities on the DEI badging for events repository.

19. Head over to your .env file and input all the credentials generated. It should look like this:
```js
appId=xxxxx
privateKey=xxxxx
clientId=xxxxx
clientSecret=xxxxx
webhookSecret=xxxxx
PORT=xxxxx
smee_URL=xxxxx
```

20. If you are using Windows OS, the start command for the project uses `NODE_ENV` to 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.
```js
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:
```js
npm install -g win-node-env
```

21. Start the app on the development envrionment using the command below:
```js
npm run dev
```
This will start the app on the development environment and connect to smee.io webhook URL.
<img width="600" src="Assets/run-badging-bot.png" alt="run-badging-bot" />

22. 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.
<img width="600" src="Assets/event-example.png" alt="testing-bot" />

23. You can also see the webhook events on the smee.io page using the URL provided in the .env file.
<img width="600" src="Assets/smee-page.png" alt="sample-smee-page" />

24. 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.js` etc where the bot comands and logic are written.

25. 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.js` file. 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:

Expand Down
152 changes: 152 additions & 0 deletions TUTORIAL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
# Tutorial

This tutorial aims to guide you through the process of setting up the bot on your local development environment in case you are using an operating system not currently supported by the bot script. If you have a linux environment and would rather use the bot script, follow the guide in the [README.md](README.md) document instead.

## Tools needed

- Node & NPM
- A GitHub account
- A [smee.io](https://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).

## Steps

### 1. Fork the Badging Bot repository
<img align="right" width="300" src="Assets/fork_badging_bot_repo.PNG" alt="fork the Badging Bot repository" />

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.

### 2. Fork the Event Diversity and Inclusion repository

<img align="right" width="300" src="Assets/fork_DEI_badging_repo.PNG" alt="fork the Badging Bot repository" />

Fork the event-diversity-and-inclusion [repository](https://github.com/badging/event-diversity-and-inclusion) by clicking on the fork button on the repository page. This is where the GitHub app will be installed to test the bot.

### 3. Clone the Badging Bot repository
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"
```

## Create a branch

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

## Generate credentials
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:

1. Head over to your Github account.

2. Go to 'Settings'.
<img width="300" src="Assets/github_profile settings.png" alt="fork the Badging Bot repository" />

3. Scroll down and click on 'Developer Settings'
<img width="300" src="Assets/developer settings.png" alt="fork the Badging Bot repository" />

4. Then, click on 'New GitHub App'.

<img width="300" src="Assets/new github app button.png" alt="fork the Badging Bot repository" />

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.

6. Enter your desired name for the app.

7. For the homepage url, input the url displayed when you started a new Smee channel on SMee.io.

<img width="300" src="Assets/app details.PNG" alt="fork the Badging Bot repository" />


8. Do the same for the webhook url.

9. Input your desired string combination as webhook secret.

10. Under 'Permissions', click on the drop down arrow for 'Repository permissions'. Grant read and write access to environments, issues, pages and webhooks.
<img width="300" src="Assets/Adjust permissions.png" alt="fork the Badging Bot repository" />

11. Under 'Subscribe to events', check 'Issues' and 'issue-comments'.
<img width="300" src="Assets/subscribe to events.png" alt="fork the Badging Bot repository" />

12. Under where can the GitHub App be installed', select 'Only on ths account'.
<img width="300" src="Assets/create github app button.png" alt="fork the Badging Bot repository" />

13. 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.

14. 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.
<img width="300" src="Assets/generate private key.png" alt="fork the Badging Bot repository" />

15. At the top left section of the page, click on the 'Install App' button. You will be redirected to this page.
<img width="300" src="Assets/Top Left Install App.png" alt="Top Left Install App" />

16. Check 'Only select repositories'.
<img width="300" src="Assets/only select repositories.png" alt="only select repositories" />

17. Search and select the diversity-and-inclusion-event repository that you forked earlier.

18. Click on Install.
<img width="300" src="Assets/install github app.png" alt="install github app" />

Now you will be able to test and use the app's functionalities on the DEI badging for events repository.

19. Head over to your .env file and input all the credentials generated. It should look like this:
```js
appId=xxxxx
privateKey=xxxxx
clientId=xxxxx
clientSecret=xxxxx
webhookSecret=xxxxx
PORT=xxxxx
smee_URL=xxxxx
```

20. If you are using Windows OS, the start command for the project uses `NODE_ENV` to 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.
```js
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:
```js
npm install -g win-node-env
```

21. Start the app on the development envrionment using the command below:
```js
npm run dev
```
This will start the app on the development environment and connect to smee.io webhook URL.
<img width="600" src="Assets/run-badging-bot.png" alt="run-badging-bot" />

22. 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.
<img width="600" src="Assets/event-example.png" alt="testing-bot" />

23. You can also see the webhook events on the smee.io page using the URL provided in the .env file.
<img width="600" src="Assets/smee-page.png" alt="sample-smee-page" />

24. 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.js` etc where the bot comands and logic are written.

25. 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.js` file. There you can state the condition or event that triggers any feature and the function that will be triggered.

26. Make sure to follow the code style, naming convention and formating guidelines as it will help the code to be readable and understandable. You can find the contributing guidelines [here](https://github.com/badging/badging-bot/blob/main/CONTRIBUTING.md).
9 changes: 9 additions & 0 deletions example_env
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
appId=
privateKey=' '
clientId=
clientSecret=
webhookSecret=secret
PORT=
smee_URL=


12 changes: 8 additions & 4 deletions index.js
Original file line number Diff line number Diff line change
Expand Up @@ -65,15 +65,19 @@ app.get("/logs", (req, res) => {
});

app.listen(process.env.PORT, () =>
logger.info(`App listening on PORT:${process.env.PORT}`)
logger.info(`App listening on PORT:${process.env.PORT}`)
);

const SmeeClient = require("smee-client");

if (process.env.NODE_ENV === "development") {
const SmeeClient = require("smee-client");

const smee = new SmeeClient({
source: "https://smee.io/badging",
target: "http://localhost:2020",
source: process.env.source,
target: `http://localhost:${process.env.PORT}`,
logger: console,
});

smee.start();
}

0 comments on commit d5979fc

Please sign in to comment.