From 37c014b452945a05b743a343505a61a025ae67cd Mon Sep 17 00:00:00 2001 From: AdeyinkaOresanya Date: Wed, 4 Oct 2023 15:08:42 +0100 Subject: [PATCH] move the tutorial to CONTRIBUTING.md file --- CONTRIBUTING.md | 158 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 156 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3aee85f..97af706 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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) +``` + +
+
+ +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 +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 + +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'. +fork the Badging Bot repository + +3. Scroll down and click on 'Developer Settings' +fork the Badging Bot repository + +4. Then, click on 'New GitHub App'. + +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. + +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. +fork the Badging Bot repository + +11. Under 'Subscribe to events', check 'Issues' and 'issue-comments'. +fork the Badging Bot repository + +12. Under where can the GitHub App be installed', select 'Only on ths account'. +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. +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. +Top Left Install App + +16. Check 'Only select repositories'. +only select repositories + +17. Search and select the diversity-and-inclusion-event repository that you forked earlier. + +18. Click on Install. +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. +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. +testing-bot + +23. You can also see the webhook events on the smee.io page using the URL provided in the .env file. +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: