From 3ef8c47d6294924bf44f75955d108c2252e885f4 Mon Sep 17 00:00:00 2001 From: Ryan Murphy Date: Wed, 5 Jul 2023 17:09:58 -0700 Subject: [PATCH] Tidy up READMEs --- CONTRIBUTING.md | 18 +++++++------ DEVELOPING.md | 24 +++++++----------- HEROKU_UPGRADE.md | 8 +++--- README.md | 64 +++++++++++++++++++++++++---------------------- SENDGRID.md | 2 ++ 5 files changed, 60 insertions(+), 56 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 64e54469..05e8d69f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,21 +10,23 @@ Our team will keep hacking on Klaxon in spare moments, and we plan to keep it hu There are several ways you can help improve Klaxon, even if you’re not a coder or you’ve never contributed to an open source project before. You can: -Help us spot bugs, including typos, and let us know by [filing an issue in Github](https://github.com/themarshallproject/klaxon/issues). If you’ve never used Github, don’t worry. Here’s a really good, quick [tutorial about discussing projects in Github Issues](https://youtu.be/KlrJVSJRUN4). Even if you’re an experienced Github user, this blog post provides some great advice on the [best practices of creating an issue](https://wiredcraft.com/blog/how-we-write-our-github-issues/). +Help us spot bugs, including typos, and let us know by [filing an issue in GitHub](https://github.com/themarshallproject/klaxon/issues). If you’ve never used GitHub, don’t worry. Here’s a really good, quick [tutorial about discussing projects in GitHub Issues](https://youtu.be/KlrJVSJRUN4). Even if you’re an experienced GitHub user, this blog post provides some great advice on the [best practices of creating an issue](https://wiredcraft.com/blog/how-we-write-our-github-issues/). -Help test the web interface, sharing feedback with us directly [in an email](mailto:klaxon-reports@themarshallproject.org) or in a Github issue. -Help prioritize new features for the community to work on together next, by commenting on ones you like in [our Github issues](https://github.com/themarshallproject/klaxon/issues). +Help test the web interface, sharing feedback with us directly [in an email](mailto:klaxon-reports@themarshallproject.org) or in a GitHub issue. +Help prioritize new features for the community to work on together next, by commenting on ones you like in [our GitHub issues](https://github.com/themarshallproject/klaxon/issues). ### Contribute code -We’re especially excited about other journalist-developers contributing code to flesh out the project and to add new features. Our motto is, “PULL REQUESTS GLADLY ACCEPTED.” +We’re especially excited about other journalist-developers contributing code to flesh out the project and to add new features. -If you want to contribute, start by reviewing this advice, inspired by this post on [the Codacy blog](http://blog.codacy.com/2015/12/17/open-source-development-a-few-guidelines/) and [Shauna Gordon-McKeon’s PyCon 2015 talk](https://shaunagm.github.io/personal/pycon2015.html). Before you do anything, read the documentation in our Github repo, particularly this CONTRIBUTING.md file and our [Code of Conduct](CODE_OF_CONDUCT.md). Once you’ve done that, you’re ready to engage with the community, by commenting on issues and participating in the process. +If you want to contribute, start by reviewing this advice inspired by this post on [the Codacy blog](http://blog.codacy.com/2015/12/17/open-source-development-a-few-guidelines/) and [Shauna Gordon-McKeon’s PyCon 2015 talk](https://shaunagm.github.io/personal/pycon2015.html). -Look for [issues](https://github.com/themarshallproject/klaxon/issues) in Klaxon’s Github repo tagged "help wanted" or “first-timer-friendly”. After you announce you’re working on an issue with a comment, fork the project. If you need help getting Klaxon running on a local development server, [follow these directions](DEVELOPING.md). Create a new branch for your feature, write a patch and send a pull request to us on Github. +Before you do anything, read the documentation in our GitHub repo, particularly this CONTRIBUTING.md file and our [Code of Conduct](CODE_OF_CONDUCT.md). You’re now ready to engage with the community by commenting on issues and participating in the process. -You can expect that we'll acknowledge your patch and respond with questions or comments, and we’ll expect that you’ll remain engaged with the issue, responding to our questions in a timely manner and iterating on the code until the patch is merged or otherwise closed. +Look for [issues](https://github.com/themarshallproject/klaxon/issues) in Klaxon’s GitHub repo tagged "help wanted" or “first-timer-friendly”. If you need help getting Klaxon running on a local development server, [follow these directions](DEVELOPING.md). Create a new branch for your feature, write a patch and send a pull request to us on GitHub. + +We should acknowledge your patch and respond with questions or comments, and we’ll expect that you’ll remain engaged with the issue, responding to our questions in a timely manner and iterating on the code until the patch is merged or otherwise closed. ### Discuss -One of the things we’re most excited about as we release Klaxon is seeing how other newsrooms put it to use. We’ll be eager to hear from you about your experiences with the tool. There are several ways we can discuss this together. You can email us directly at [klaxon-reports@themarshallproject.org](mailto:klaxon-reports@themarshallproject.org). We also have a [Google Group email list](https://groups.google.com/forum/#!forum/news-klaxon-users) where Klaxon users and developers working on the project can talk. Users can ask questions of one another, and contributors can discuss changes to the code and adding new functionality. Finally, you can always open or comment on an item in our [Github repo’s issue tracker](https://github.com/themarshallproject/klaxon/issues). \ No newline at end of file +One of the things we’re most excited about as we release Klaxon is seeing how other newsrooms put it to use. We’ll be eager to hear from you about your experiences with the tool. There are several ways we can discuss this together. You can email us directly at [klaxon-reports@themarshallproject.org](mailto:klaxon-reports@themarshallproject.org). We also have a [Google Group email list](https://groups.google.com/forum/#!forum/news-klaxon-users) where Klaxon users and developers working on the project can talk. Users can ask questions of one another, and contributors can discuss changes to the code and adding new functionality. Finally, you can always open or comment on an item in our [GitHub repo’s issue tracker](https://github.com/themarshallproject/klaxon/issues). diff --git a/DEVELOPING.md b/DEVELOPING.md index 9de28cba..dab787c8 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -2,15 +2,11 @@ If you're interested in [helping improve Klaxon by contributing code](CONTRIBUTING.md), this is a quick guide to how to get it running on your local machine for development. -First, we'll assume you already have git on your local machine, as well as a standard postgres installation (if you need a [quick way to get Postgres up and running, try this](https://postgresapp.com/)). So go to your terminal, navigate to whatever directory where you keep your projects and clone the Klaxon repo. +First, we'll assume you already have git on your local machine, as well as PostgreSQL (if you need a [quick way to get Postgres up and running, try this](https://postgresapp.com/)). Go to your terminal, navigate to the directory where you keep projects and clone the Klaxon repository. -``` -git clone git@github.com:themarshallproject/klaxon.git -``` +After you've cloned it move into the Klaxon directory. If you're on a Mac, you'll need to already have [homebrew](https://brew.sh/) and [rbenv](https://github.com/rbenv/rbenv) (a program that manages versions of Ruby) installed. Then you'll want -After you've cloned it, `cd` into the Klaxon directory. If you're on a Mac, you'll need to already have [homebrew](https://brew.sh/) and [rbenv](https://github.com/rbenv/rbenv) (a program that manages versions of Ruby) installed. Then you'll want - -These next commands will put the proper (albeit aged) version of Ruby that Klaxon requires on your machine and make it available in this repo's directory. +These next commands will install the version of Ruby that Klaxon requires on your machine and make it available in this directory. ``` brew update && brew upgrade ruby-build @@ -31,29 +27,27 @@ ADMIN_EMAILS="my_awesome_email@gmail.com" HOST='localhost:5000' ``` -Feel free to substitute in your email address. In development, Klaxon doesn't actually send emails locally, so a real address is not required. - -Now that's set, you'll run a couple of commands for Rails to create Klaxon's database on your machine. +Feel free to substitute in your email address. In development, Klaxon doesn't actually send emails locally so a real address is not required. You just need to make sure you use exactly the same thing when you log in to the admin interface locally. With that set you'll run a couple of commands to create Klaxon's database on your machine. ``` bin/rake db:create bin/rake db:migrate ``` -Now, you should be about ready to get started. This command in the top folder of the Klaxon repo will get your dev server rolling. +You're about ready to get started. This command in the top folder of the Klaxon repo will start the development server. ``` bin/dev ``` -Now, you should be able to go to [localhost:5000](http://localhost:5000/) in your web browser and see Klaxon's welcome screen pop up. You'll want to manually add a webpage or two to watch at [watching/pages/new](http://localhost:5000/watching/pages/new). For development purposes, you'll probably want to pick a site that updates pretty regularly. We use [http://www.timeanddate.com/](http://www.timeanddate.com/). +Visit [localhost:5000](http://localhost:5000/) in your web browser and you should see Klaxon's welcome screen. Log in using the email you set above. Try to manually add a webpage or two at [watching/pages/new](http://localhost:5000/watching/pages/new). For development purposes you'll probably want to pick a site that updates pretty regularly — we use [http://www.timeanddate.com/](http://www.timeanddate.com/). -To get Klaxon to check for updates on the pages you're watching, in another terminal window, run this rake command. +To get Klaxon to check for updates on the pages you're watching, in another terminal window run this command: ``` rake check:all ``` -Now, when you go to the main Klaxon page, you should start to see changes in the Feed of the latest updates. +When you go to the main Klaxon page you should see new changes in the feed. -Go forth and add some features, and be sure to send us your [pull requests](/pulls) for features you think other Klaxon users might find handy. +Go forth and add some new features! diff --git a/HEROKU_UPGRADE.md b/HEROKU_UPGRADE.md index 0e58b851..85ba12f3 100644 --- a/HEROKU_UPGRADE.md +++ b/HEROKU_UPGRADE.md @@ -1,6 +1,8 @@ -Those of you who are still running Klaxon on free Heroku tiers have likely received messages telling you that the free services will soon be wound down. We have considered a few options to work around this, but we haven't found a good way to mitigate this issue while keeping Klaxon as easy to deploy and maintain as can be. After six years of being able to run this at no cost at all, it looks like you will now have to pay a small fee to continue to do so. We will keep investigating other avenues for the future of Klaxon, but for now, you'll have to pay. +# Heroku Transition Guide -On Nov. 28th, Heroku will stop running free apps, so you have to make a couple of small tweaks to your setup before then. Here's what you'll need to do: +Those of you who are still running Klaxon on free Heroku tiers have likely received messages telling you that the free services will soon be wound down. We have considered a few options to work around this, but we haven't found a good way to mitigate this issue while keeping Klaxon as easy to deploy and maintain as can be. After six years of being able to run this at no cost at all, it looks like you will now have to pay a small fee to continue to do so. We will keep investigating other avenues for the future of Klaxon, but for now, you'll have to pay. + +On Nov. 28th, Heroku will stop running free apps, so you have to make a couple of small tweaks to your setup before then. Here's what you'll need to do: - Log into your Heroku dashboard at https://dashboard.heroku.com/apps/ - Click on your Klaxon app @@ -8,4 +10,4 @@ On Nov. 28th, Heroku will stop running free apps, so you have to make a couple o - You should see a list of services that run as part of your setup. First, you'll need to click "Change Dyno Type" It will present you with a menu of options. You'll probably want to choose "Eco". This will cost you $5 per month and can be shared across several apps, if you're using Heroku for any other free programs. It will also put your web app to sleep if someone doesn't visit for 30 minutes (this is the same way the free-tier dynos worked). But it should keep your Klaxon scheduler and notifier running as expected. - Many of you have likely already outgrown the 10,000-row database limit for the free Postgres starter plan. If, however, you're still using that free database, you'll need to upgrade that too. Look at the line that says "Heroku Postgres". You should see an orange alert on the right-hand side of the table that reads "Hobby Dev". Click the menu button to the right of the word "Free" and choose "Modify Plan". There you'll need to change your plan name from "Hobby Dev" to "Mini" and click "Provision". The Mini Postgres plan costs about $5 a month for 10,000 rows. When you outgrow that database, you can upgrade to the Basic Postgres plan for about $9 a month. -We hope this helps you get everything sorted to keep your Klaxon running. If you have questions or need a hand with these changes, reach out to Tom directly, and we'll do our best to help you troubleshoot. \ No newline at end of file +We hope this helps you get everything sorted to keep your Klaxon running. If you have questions or need a hand with these changes, reach out to Tom directly, and we'll do our best to help you troubleshoot. diff --git a/README.md b/README.md index e39e1786..28d10229 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,16 @@ ## Get emailed when a website changes -Klaxon is a free, quick to set up and easy to use _robot_ that checks websites regularly so you don't have to. +Klaxon is a free, quick to setup and easy to use service that checks websites for changes so you don't have to. -You list websites you want monitored and Klaxon will visit them and, if they change, email you what's different. It saves you having to reload dozens of links yourself every day. +You add websites you want monitored and Klaxon will visit them periodically. If they change, it'll email you what's different. It's perfect for monitoring website changes you might miss — like freedom of information disclosure logs, court records or anything related to Donald Trump. It can even send notifications to Slack and Discord channels with a little extra setup. -It's perfect for monitoring website changes you might miss, like freedom of information disclosure logs, court records, and anything related to Donald Trump. And it can even send notifications to your Slack and Discord channels. - -Read more below, or say hello to the humans behind the project at the [Google Group email list](https://groups.google.com/forum/#!forum/news-klaxon-users). +Read more below or say hello to the humans behind the project at the [Google Group email list](https://groups.google.com/forum/#!forum/news-klaxon-users). [![](docs/klaxon_hero.png)](https://newsklaxon.org) ## Alerting journalists to changes on the web -Built and refined in the newsroom of [The Marshall Project](https://www.themarshallproject.org/), Klaxon has provided our journalists with many news tips, giving us early warnings and valuable time to pursue stories. Klaxon has been used and tested by journalists at The Marshall Project, The New York Times, the Texas Tribune, the Associated Press [and elsewhere](NEWSROOMS.md). +Built and refined in the newsroom of [The Marshall Project](https://www.themarshallproject.org/), Klaxon has provided our journalists with many news tips, giving us early warnings and valuable time to pursue stories. Klaxon has been used and tested by journalists at The Marshall Project, The New York Times, The Texas Tribune, Associated Press, [and more](NEWSROOMS.md). The public release of this free and open-source software was supported by Knight-Mozilla [OpenNews](https://opennews.org/). @@ -20,42 +18,44 @@ The public release of this free and open-source software was supported by Knight Klaxon enables users to "bookmark" portions of a webpage and be notified (via email, [Slack, or Discord](#notify-a-slack-or-discord-channel)) of any changes that may occur to those sections. [Learn more about bookmarklets on the help.md page](data/help.md). -[![Deploy](https://www.herokucdn.com/deploy/button.png)](https://heroku.com/deploy?template=https://github.com/themarshallproject/klaxon/tree/master) +[![Deploy](https://www.herokucdn.com/deploy/button.png)](https://heroku.com/deploy?template=https://github.com/themarshallproject/klaxon/tree/main) ## Setting up your Klaxon -Klaxon is open source software built in the newsroom of [The Marshall Project](https://www.themarshallproject.org/), a nonprofit investigative news organization covering the American criminal justice system. It was created by a team of three—Ivar Vong, Andy Rossback and Tom Meagher—and it is subject to the kind of shortcomings any young, small side project might encounter. It may break unexpectedly. It may miss a change in a website, or an email might not fire off correctly. Still, we’ve found it immensely useful in our daily reporting. We want other journalists to benefit from Klaxon and to help us improve it, but keep these caveats in mind and use it at your own risk. +Klaxon is open-source software built by the newsroom of [The Marshall Project](https://www.themarshallproject.org/), a nonprofit investigative news organization covering the American criminal justice system. It was created by a team of three — Ivar Vong, Andy Rossback and Tom Meagher — and it is subject to the kind of shortcomings any side project might encounter. It may break unexpectedly. It may miss a change in a website or an email might not fire off correctly. Still we’ve found it immensely useful in our daily reporting. We want other journalists to benefit from Klaxon and to help us improve it, but keep these caveats in mind and use it at your own risk. -Our team will keep hacking on Klaxon in spare moments, and we plan to keep it humming for our own use. But we think this project has the potential to help just about any newsroom. For it to succeed and to evolve, it will depend on the contributions from other journalist-developers. We are excited about the prospect of building a community around this project to help maintain it. So when you spot the inevitable bug, please let us know. And if you’d like to help us [make this better](CONTRIBUTING.md), or add new functionality to it, we’d love to have your help. +Our team hacks on Klaxon in spare moments and we plan to keep it humming for our own use. But we think this project has the potential to help just about any newsroom. For it to succeed and to evolve it will depend on the contributions from other journalist-developers. We are excited about the prospect of building a community around this project to help maintain it. So when you spot the inevitable bug, please let us know. And if you’d like to help us [make this better](CONTRIBUTING.md) or add new functionality to it we’d love to have your help. ### Getting started -One of our goals for Klaxon is to make it as easy as possible for reporters and editors without tech backgrounds to use and to set up. Getting your own Klaxon running in your newsroom will require you to run a handful of instructions one time through the help of online services Heroku and Github. Following these directions, it should take maybe 10 minutes to set up your Klaxon, including the time to create accounts on Heroku and Github if you need to. +One of our goals for Klaxon is to make it as easy as possible for reporters and editors without tech backgrounds to use and to setup. Getting your own Klaxon running in your newsroom will require you to run a handful of instructions one-time through the help of online services Heroku and GitHub. It should take maybe 10 minutes to set up your Klaxon, including the time to create accounts on Heroku and GitHub if you need to. + +We use [Heroku](https://heroku.com/) to deploy software at The Marshall Project. We think it makes some of the tedious work of running servers a lot easier to deal with so we designed Klaxon to be easily deployable on Heroku. (If you’d like to run this in your newsroom’s preferred server setup — say using [Docker](https://github.com/themarshallproject/klaxon/blob/develop/DOCKER.md) or a [Linux machine](https://github.com/themarshallproject/klaxon/blob/develop/install_on_ubuntu.md) — we encourage you to do so, but know you'll be on your own maintaining it!) -We use [Heroku](https://heroku.com/) to deploy software in The Marshall Project newsroom. We think it makes some of the tedious work of running servers a lot easier to deal with, so we designed Klaxon to be easily deployable on Heroku. (If you’d like to run this in your newsroom’s preferred server setup — say using [Docker](https://github.com/themarshallproject/klaxon/blob/develop/DOCKER.md) or a [Linux machine](https://github.com/themarshallproject/klaxon/blob/develop/install_on_ubuntu.md) — we encourage you to do so, and to send it back to us, with documentation, [in a pull request](CONTRIBUTING.md).) If you want to use our setup, you’ll need to [create an account with Heroku](https://signup.heroku.com/), if you don’t already have one. +If you want to use our setup, you’ll need to [create an account with Heroku](https://signup.heroku.com/) if you don’t already have one. ### How much will this cost? -While Heroku no longer offers free tiers of service, this should cost about $10 a month to get started. If you start using it a lot, you may need to pay a small amount to move to a bigger databse. Out of the box with Heroku, for $10 you’ll get: +Heroku unfortunately no longer offers a free tier, so you will need to be able to pay around $10 a month to get started. Out of the box with Heroku you’ll get: - 12,000 emails per month with SendGrid - 10,000 records of changes in your Postgres database -- Your web interface -- Checks of each of your watched sites every 10 minutes with Heroku’s Scheduler. +- A web interface +- A scan of each watched site every 10 minutes -If you find your newsroom hitting the limits of these tiers, you can pay to expand them. To send up to 40,000 emails a month, you can upgrade your Sendgrid add-on in Heroku for $9.95 a month. If you need to store more records in your database, you can pay an additional $4 a month for up to 10 million rows. And if you need your web interface running around the clock, you can upgrade your Heroku dyno from the Eco to the Hobby level for $2 more a month. Some of these won’t be necessary, particularly in smaller newsrooms, but it’s good to know. +If you find your newsroom hitting the limits of these tiers you can pay to expand them. To send up to 40,000 emails a month you may upgrade your Sendgrid add-on in Heroku for $9.95 a month. If you need to store more records in your database you can pay an additional $4 a month for up to 10 million rows. And if you need your web interface running around the clock, you can upgrade your Heroku dyno from the Eco to the Hobby level for $2 more a month. This likely won't be necessary — particularly in smaller newsrooms — but it’s good to know. ### Let’s do this -If you have a Heroku account and you’re ready to go, it’s time to click on this button: +If you have a Heroku account you’re ready to go — it’s time to click on this button: -[![Deploy](https://www.herokucdn.com/deploy/button.png)](https://heroku.com/deploy) +[![Deploy](https://www.herokucdn.com/deploy/button.png)](https://heroku.com/deploy?template=https://github.com/themarshallproject/klaxon/tree/main) -You must be logged into your Heroku account, and it will take you to a page to configure your new app in Heroku’s dashboard. First, give your app a name in the first box. While this is technically optional, this will also double as the URL for your Klaxon instance, so think carefully about it for a moment. Try maybe an abbreviation for your newsroom with a hyphen and the word klaxon, like “wp-klaxon” or “sl-klaxon”. This will become a URL as https://sl-klaxon.herokuapp.com/ +It will take you to a page to configure your new app in Heroku’s dashboard. First, give your app a name in the first box. While this is technically optional, this will also double as the URL for your Klaxon instance, so think carefully about it for a moment. Try maybe an abbreviation for your newsroom with a hyphen and the word klaxon, like “wp-klaxon” or “sl-klaxon”. This will become a URL as https://sl-klaxon.herokuapp.com/ -Scroll down to the “\* Admin_emails” field, add a comma-separated list of email addresses for your newsroom’s Klaxon administrators. These administrators will be able to create accounts for any user in your organization, as well as configure various Klaxons and integrations with services like Slack and Discord. +Scroll down to the `admin_emails` field and add a comma-separated list of email addresses of your newsroom’s Klaxon administrators. These administrators will be able to create accounts for users in your organization as well as configure the Slack and Discord integrations. -Click the big purple “Deploy for Free” button. If you haven’t given Heroku your credit card yet, it will ask you for your information now. After that, give Heroku a few minutes for the app to build. +Click the big purple “Deploy" button. If you haven’t given Heroku your credit card yet it will ask you for your information now. After that, give Heroku a few minutes for the app to build. When you see this message: @@ -63,11 +63,15 @@ When you see this message: ...you’re almost done. -Click on the button that says “Manage App”. This takes you behind the scenes of the various components powering your Klaxon. On this resources screen, click on the link for “Heroku Scheduler,” which will take you a new screen where you must add the very important piece. The scheduler is what runs every 10 minutes to actually check all the sites and pages you’re watching. Click the long, purple ‘Add new job” button. In the text box next to the dollar sign, type the words “rake check:all” with the colon and without the quotes. Under “Frequency,” change it from “Daily” to “Every 10 minutes”. Click the purple “Save” button and your scheduler item should look like this: +Click on the button that says “Manage App”. This takes you behind the scenes of the various components powering your Klaxon. On this resources screen, click on the link for “Heroku Scheduler,” which will take you a new screen where you must add the very important piece. The scheduler is what runs every 10 minutes to actually check all the sites and pages you’re watching. Click the long, purple "Add new job" button. In the text box next to the dollar sign, type the words “rake check:all” with the colon and without the quotes. Under “Frequency” change it from “Daily” to “Every 10 minutes”. Click the purple “Save” button and your scheduler item should look like this: ![](docs/scheduler.png) -Unfortunately our email provider Sendgrid now requires an additional step to confirm that you are not a spammer. Your new Sendgrid account is now in a "suspended" state, and to get it unsuspended you have to contact [Sendgrid support](https://support.sendgrid.com/hc/en-us/requests/new#login-issue). You can do this by clicking the Sendgrid logo on the Resources tab. If clicking on the logo takes you to an error page, do not worry. This has been known to happen as Sendgrid's system has undergone redesigns. Instead, go to [Sendgrid's page to ask for support](https://support.sendgrid.com/hc/en-us/requests/new#login-issue). Be sure to use the same email address associated with your Heroku account and provide the url of your Klaxon instance. When they ask for "Business impact," choose "P3 General - You have a question about Sendgrid or how to use its products". This step is a nuisance, but important. **You will not be able to get an email log in to Klaxon until you are cleared by Sendgrid.** This usually happens pretty quickly (hours not days). +Sendgrid now requires an additional step to confirm that you are not a spammer. Your new Sendgrid account is created in a "suspended" state. To get it unsuspended you have to contact [Sendgrid support](https://support.sendgrid.com/hc/en-us/requests/new#login-issue). You can do this by clicking the Sendgrid logo on the Resources tab. + +If clicking on the logo takes you to an error page do not worry. This has been known to happen as Sendgrid's system has undergone redesigns. Instead go to [Sendgrid's page to ask for support](https://support.sendgrid.com/hc/en-us/requests/new#login-issue). Be sure to use the same email address associated with your Heroku account and provide the url of your Klaxon instance. When they ask for "Business impact," choose "P3 General - You have a question about Sendgrid or how to use its products". + +This step is a nuisance, but important. **You will not be able to get an email log in to Klaxon until you are cleared by Sendgrid.** This usually happens pretty quickly. Unfortunately you are not yet done configuring Sendgrid. There are more steps to set up your account. @@ -79,7 +83,7 @@ Unfortunately you are not yet done configuring Sendgrid. There are more steps to 6. Change the `SENDGRID_PASSWORD` variable to the API Key by clicking the pencil icon next to it, pasting it in, and saving it. 7. Change the `SENDGRID_USERNAME` variable to the string "apikey" in the same manner. -Now you'll need to set up a "Verified Sender" account in Sendgrid using an email address that you have access to. In your Sendgrid dashboard, click "Sender Authentication" and choose "[Verify Single Sender](https://app.sendgrid.com/settings/sender_auth/senders/new)." (See https://github.com/themarshallproject/klaxon/issues/404 for some more context.) +Next you'll need to set up a "Verified Sender" account in Sendgrid using an email address that you have access to. In your Sendgrid dashboard, click "Sender Authentication" and choose "[Verify Single Sender](https://app.sendgrid.com/settings/sender_auth/senders/new)." (See https://github.com/themarshallproject/klaxon/issues/404 for some more context.) When you've completed this process in Sendgrid, you'll need to set the `MAILER_FROM_ADDRESS` variable as you did above to your verified sender email address. @@ -99,11 +103,11 @@ On the right side of the page, click the “Create New User” button. Add the r #### Limit new users to only those on specific email domain(s) -By default, people with any email address can be added as new users. If you'd like to allow only users with _specific_ email domains, set the `APPROVED_USER_DOMAINS` environment variable (or "Config Variable" in Heroku's lingo). That variable should be a comma-separated list of domains, e.g., `themarshallproject.org,nsa.gov`. +By default, people with any email address can be added as new users. If you'd like to allow only users with _specific_ email domains, set the `APPROVED_USER_DOMAINS` environment variable (or "Config Vars" in Heroku's lingo). That variable should be a comma-separated list of domains, e.g., `themarshallproject.org,nsa.gov`. ### Notify a Slack or Discord channel -You’re all set for email notifications. If you’d like to also receive alerts through Slack and/or Discord, you can set that up now too. (If you want alerts from other services, [we welcome pull requests](CONTRIBUTING.md)) Click on the “Settings” button in the upper right corner of the page and choose “Integrations” from the menu. On the Integrations page, click the “Create Slack Integration” button. You can add an integration for any number of channels in your newsroom’s Slack or Discord. For each channel, you just have to set up an Incoming Webhook. +You’re all set for email notifications. If you’d like to also receive alerts through Slack and/or Discord you can set that up now. Click on the “Settings” button in the upper right corner of the page and choose “Integrations” from the menu. On the Integrations page, click the “Create Slack Integration” button. You can add an integration for any number of channels in your newsroom’s Slack or Discord. For each channel, you just have to set up an Incoming Webhook. #### Slack @@ -121,19 +125,19 @@ Now, choose the name for your webhook (you can leave it the default random name When we release major changes to Klaxon, we’ll make an announcement to [our Google Group email list](https://groups.google.com/forum/#!forum/news-klaxon-users). At that point, you’ll likely want to adopt those in your system as well. If you're comfortable using git on the command line, this would require just a few simple commands: pull the changes from the master branch of this repo, merge them into your forked repo and push it all to Heroku. -But if you're not a programmer, there is still a fairly painless way to upgrade by using Github and Heroku. First, you’ll need to fork our repo to your own Github account to receive the updates, and then you can use Heroku’s dashboard to push the changes to your application. +But if you're not a programmer, there is still a fairly painless way to upgrade by using GitHub and Heroku. First, you’ll need to fork our repo to your own GitHub account to receive the updates, and then you can use Heroku’s dashboard to push the changes to your application. -If you don’t already have an account at [Github.com](https://github.com/), now is a good time to set one up (don’t worry, it’s free). This has the added benefit of giving you access [to comment on the issues](https://github.com/themarshallproject/klaxon/issues) our community is working on developing. Once you’re logged into Github with your new account, go to [the repo for the Klaxon project](https://github.com/themarshallproject/klaxon) and click the “Fork” button. This copies our code into a separate version under your Github account that you can tie to your Klaxon instance running on Heroku’s servers. +If you don’t already have an account at [GitHub](https://github.com/) now is a good time to set one up (don’t worry, it’s free). This has the added benefit of giving you the ability [to comment on issues](https://github.com/themarshallproject/klaxon/issues). Once you’re logged into GitHub with your new account, go to [the repo for the Klaxon project](https://github.com/themarshallproject/klaxon) and click the “Fork” button. This copies our code into a separate version under your GitHub account that you can tie to your Klaxon instance running on Heroku’s servers. Now, go to [https://dashboard.heroku.com](https://dashboard.heroku.com/) and choose your application (remember, the one you named when you first set up Klaxon, probably sl-klaxon or something similar if you followed our advice above). From the menu of options at the top of the page, click on the “Deploy” button. Look for section called “Deployment method,” which should be the second from the top of the Deploy page. -You should see three buttons. Click the one in the middle that says “Github Connect With Github”. The options at the bottom of the page will change. Now, click the gray button that says “Connect To Github”. It will pop up a new window to log you into Github, if you aren’t already. In that window, click the “Authorize Application” button. The popup window should now close itself. +You should see three buttons. Click the one in the middle that says “GitHub Connect With GitHub”. The options at the bottom of the page will change. Now, click the gray button that says “Connect To GitHub”. It will pop up a new window to log you into GitHub, if you aren’t already. In that window, click the “Authorize Application” button. The popup window should now close itself. -On the Heroku page, in the “Connect to Github” section at the bottom, type ‘klaxon’ into the search box next to your Github username. Click the “Search” button. Next, click the “Connect” button next to the name of your forked repo that pops up below. Finally, select the 'master' branch from the dropdown and click “Enable Automatic Deploys” button in the “Automatic deploys” section. This ties your Heroku server to your Github account, so that every time you merge updates into your forked version of the Klaxon repository, they will automatically go live on your server with the latest updates. You'll only have to do all of this one time to set up the pipeline. +On the Heroku page, in the “Connect to GitHub” section at the bottom, type ‘klaxon’ into the search box next to your GitHub username. Click the “Search” button. Next, click the “Connect” button next to the name of your forked repo that pops up below. Finally, select the 'master' branch from the dropdown and click “Enable Automatic Deploys” button in the “Automatic deploys” section. This ties your Heroku server to your GitHub account, so that every time you merge updates into your forked version of the Klaxon repository, they will automatically go live on your server with the latest updates. You'll only have to do all of this one time to set up the pipeline. _Note: if you are upgrading from version 0.2.0 or lower, please follow the additional instructions in [migration_setup.md](migration_setup.md)_ -Finally, each time an update is announced on the Google Group, you can go to your forked version of the repo on Github and click the green “New Pull Request” button to pull the changes from our master repo. +Finally, each time an update is announced on the Google Group, you can go to your forked version of the repo on GitHub and click the green “New Pull Request” button to pull the changes from our master repo. On the "basefork" dropdown on the left, click and select your repo. Then click the “compare across forks” link and change the “head fork” on the dropdown menu to “marshallproject/klaxon”. Make sure both the branches are set to “master” (they should already be). Below that, a green checkbox and the words “Able to merge” should appear. If they do, click the green “Create Pull Request” button. Give this pull request a title. You might want to say “Merging Klaxon release 0.9.1” or whatever the new version number is and click the “Create Pull Request” button again. diff --git a/SENDGRID.md b/SENDGRID.md index f378de47..2ef50ad6 100644 --- a/SENDGRID.md +++ b/SENDGRID.md @@ -1,3 +1,5 @@ +# Sendgrid + Sendgrid requires that you authenticate using an API key, instead of the user name and password that they automatically provide through the plugin. Unfortunately this means that some manual steps are required to properly configure your Klaxon instance. You will create an API key for Sendgrid, and set it as the Sendgrid password. 1. From the Heroku application page, click on the "Resources" tab, and click the link to the Sendgrid plugin, this will take you to the Sendgrid website, which will ask you to update your email. Be sure to put your real email address you use for Klaxon.