Winds – An in Depth Tutorial on Making Your First Contribut
栏目分类：资料 发布日期：2018-08-02 浏览次数：次
本文为去找网小编(www.7zhao.net)为您推荐的Winds – An in Depth Tutorial on Making Your First Contribution to Open-Source Software，希望对您有所帮助，谢谢！ 内容来自www.7zhao.net
The team here at enjoys building open-source sample applications to showcase the functionality of our API. Our perspective has always been that it’s better to demonstrate the capabilities of our offerings in a fully functional platform. In this case, leveraging Stream and other great services allowed us to build a podcast and RSS reader, , in months rather than years. In addition, as an project, Winds keeps getting better thanks to contributions from its growing user base (now over 14,000 users and ~5,500 stars!). 去找(www.7zhao.net欢迎您
In this post, we’ll give you a rundown on how Winds – Stream’s most popular open-source sample application – is built. If you’re not familiar with Winds, you can read more about it . We’ll start with a detailed walkthrough on adding a feature that requires us to touch multiple aspects of the application’s front and backend.
By the end of this post, you’ll be ready to add your own features to Winds and contribute to the open-source community! Whether you’re a new coder or a veteran, we are confident you’ll learn something new. :grinning:
Please note, this tutorial assumes the following : 欢迎访问www.7zhao.net
- You’re running macOS or understand how to install the various required dependencies on your OS of choice. :gift:
- You have a basic understanding of React (it’s okay if you don’t, but it helps) :computer:
- You have an understanding of git (we won’t be diving deep, but general knowledge is required). :flashlight:
- You’re super stoked to learn how to code against the Winds codebase! :boom:
Let’s get started! 内容来自www.7zhao.net
As you may know, system-wide dependencies are required for every application. To ensure that we stay on track, let’s only cover installations for macOS.
For those of you who are new to coding, is an amazing tool for handling installations of system dependencies. In a single command, you can install a coding language of your choice, or use Homebrew’s Cask functionality to install full-blown applications on your machine. If you don’t have Homebrew installed, you can install it with the following command: 本文来自去找www.7zhao.net
Once you’ve got Homebrew all squared away, we can move on to the next step…
Node.js is heavily used throughout this project – mostly for the API and test suite. With that said, let’s make sure you’re running the latest version of node. At the time of writing this, Node.js is at v10.7.0 (and changing often).
If you have Node.js installed, you can check your node version with the following command: 内容来自www.7zhao.net
Note : We’ll assume that you are running the latest version of node.
If you don’t have Node.js installed, you can do so with one of the following ways:
b) NVM (Recommended)
NVM or Node Version Manager is a popular and open-source tool. It allows you to jump around between Node.js versions with a short command. Everything is documented . Installing is as easy as following these steps: copyright www.7zhao.netStep 1
本文来自去找www.7zhao.netInstall the latest version of Node.js:
Pro Tip : You can run the command nvm ls-remote and it will list out all versions, including new versions, in your console.
Now if you run node –version , you should see the latest version that you installed.
is our primary datastore for user data, RSS, Podcasts, and much more. We use MongoDB Atlas, a hosted version of MongoDB built and maintained by MongoDB. 内容来自www.7zhao.net
Note : The command to start MongoDB is brew services start MongoDB .
is important as it serves as our job queue for processing RSS and Podcast feeds. We also use Redis for some basic caching on items that are not updated (such as interests). 内容来自www.7zhao.net
Note : The command to start Redis is simply redis-server . A full list of commands can be found . 欢迎访问www.7zhao.net
is a replacement for npm (node package manager). We recommend yarn over npm as we have found it to be more reliable and an overall better package manager for Node.js dependencies. copyright www.7zhao.net
Global Yarn Dependencies :earth_americas:
There’s one Node.js dependency that we need to be local, and for that, we’ll use . The dependency is , a process manager that we’ll talk about in a bit. For now, run the following command to install PM2: 去找(www.7zhao.net欢迎您
Clone the Repo :floppy_disk:
You now have all of the necessary dependencies installed, so let’s go ahead and clone the repository. You can grab the URL from , or you can use the command below (just make sure that you’re cloning into a directory that makes sense for you (e.g. ~/Code)). 去找(www.7zhao.net欢迎您
If all goes well, your terminal will look similar to this screenshot: www.7zhao.net
Setting Up Third-Party Services :man::man::girl::boy:
Winds relies on a couple of third-party resources to run. All external services will have API Keys/Secrets and other values that you will need to save for later in the post – I recommend using the Notes app in macOS. In total, it’ll take about 15-20 minutes for you to complete. 内容来自www.7zhao.net
Note : All services required to run Winds are free up to a certain level (generally production numbers), so no need to worry about fees for now. None of the services we recommend using will require a credit card. 去找(www.7zhao.net欢迎您
1. Mercury Web Parser (~2 minutes)
by plays a large role in Winds. It ensures that all RSS articles we parse are stripped of script tags and other messy code that is injected into HTML prior to rendering.
To sign up for Mercury, head over the and click “Sign Up”. Once you’ve completed that, grab the provided API key and save it somewhere special.
Step 2: 本文来自去找www.7zhao.netSave the generated API key.
2. Stream (~5 minutes)
powers the feeds within the application, along with the personalized content suggestions
Step 2: www.7zhao.netClick on “View Dashboard” as highlighted in the screenshot below. Or, play around with the API first. :grinning:
本文来自去找www.7zhao.netClick “Create App” and fill in the details. Please note that the app name must be globally unique – I recommend prefixing it with your name as this will be a test project.
: 内容来自www.7zhao.netNext, we need to configure our “ ” within Stream. The required feed groups are located on .
- podcast (flat)
- rss (flat)
- user (flat)
- timeline (flat)
- user_episode (flat)
- user_article (flat)
You’ll also want to grab your App ID , which is located at the top of the page and store the value. copyright www.7zhao.net
That’s it for Stream! www.7zhao.net
3. Algolia (~10 minutes)
Algolia powers search for Winds. It’s a crucial piece of technology for the application and plays a major role in the user experience.
: copyright www.7zhao.netAlgolia is super easy to set up; we just need to head over to their to create an account.
Step 2: 去找(www.7zhao.net欢迎您Next, fill out the info required by Algolia.
去找(www.7zhao.net欢迎您Choose your data center. For the purpose of this tutorial, it doesn’t matter; however, I’m going to select the closest to me which is US-Central.
copyright www.7zhao.netStep 4
: www.7zhao.netSelect “Other” as the type of application you are building and “As soon as possible” in the drop-down. Then click “Finish” to wrap things up.
: www.7zhao.netThe next step in this process is creating an index, which is where all of the Winds searchable data will live. To bypass the onboarding process, head directly to the dashboard . Then click on the “Indices” button in the left-hand column. Once the page loads, click on the “Add New Index” button to generate an index. Name this whatever you want, but make sure you can write down the name of your index. I’m going to name mine “dev_Winds”.
: 本文来自去找www.7zhao.netThe last step in the process is grabbing our “Application Name”, “Search-Only API Key” and “Admin API Key”. Both can be found under “API Keys” on the right-hand side of the page under the “API Keys” section. Keep these credentials handy for later use in the setup process.
4. Sentry (~2 minutes)
Sentry is another one of the most important tools in our toolbox. Sentry captures errors that occur in the backend API, allowing us to jump on bug fixes before users even know. 去找(www.7zhao.net欢迎您Step 1
: copyright www.7zhao.netCreate a new account .
copyright www.7zhao.netGive your project a name. I’m calling mine “Winds” because, well, we’re working on the Winds project. :grinning:
Click “Create Project” and you will be redirected. 去找(www.7zhao.net欢迎您Step 3
: 内容来自www.7zhao.netGet your DSN by clicking on the link in “ Already have things set up? Get Your DSN.”
Copy this value, as we’ll need it in the coming sections.
Cloning the Repo :dvd:
To get started with next steps, you’ll need to clone the repository from GitHub. You can use the following command to do so: 内容来自www.7zhao.net
Great! Now that you’ve cloned the repo, let’s go ahead and install the required dependencies with yarn. copyright www.7zhao.net
You’ll want to move into the /api directory and run the yarn command. Here’s a little snippet that will help you:
Assuming you’re in the /api directory, you can move out and into the /app directory to do a yarn install. 本文来自去找www.7zhao.net
Note : API and App have separate package.json files. While this can be confusing, it’s necessary so that we don’t bloat each directory – even though they are in the same repository, the directories are deployed as separate applications.
Before we move on, I’d like to take a minute to discuss the front- and back-end structure of the site. With any application, it’s important to understand the architecture and thought process behind it.
The front end portion of Winds is pretty straightforward. We used Create React App (CRA) to bootstrap the application and then start the development process. The frontend code can be found here:
The backend API is slightly more complicated than the frontend. Aside from being powered by Node.js, the backend handles nearly all of the business logic – communicating with third-party services, orchestrating workers for parsing RSS, Podcasts, and Open Graph data, etc. The backend can be viewed here: .
Almost all of the code that we use is written in ES6. This allows us to keep our footprint small while maintaining readable code.
Routes are rather simple. They do what the name suggests – route requests to the desired destination. Here’s a short example of a route file:
Note : The route is wrapped in a wrapAsync() function. This function captures any errors that bubble up and sends them to Sentry.
The controllers are called by the route files and contain most, if not all of the business logic within the API. The controllers communicate with the models, which allow them to talk to the database.
Models are, essentially, the core foundation of the API. They provide the structure for the backend datastore (MongoDB) by enforcing what are known as “schemas”. Schemas contain various types, such as “String”, “Boolean”, etc. Here’s a short example of our user schema (I removed some of the helper functions to shorten the example, so be sure to look at the code to see them): 内容来自www.7zhao.net
For a full list of Schema Types, have a look at the . copyright www.7zhao.net
The workers perform very special tasks that would otherwise be blocking processes. For example, we use dedicated tasks for processing RSS feeds, Podcast feeds, Open Graph Images, and more. Without having dedicated processes for these tasks, our API would quickly come to a halt and users would not receive a response message in a timely manner – the API would likely timeout.
Our workers use , a queueing infrastructure for Redis. Basically, our API inserts a call to Redis using the Bull Node.js library, then our workers pick up the job and process it asynchronously. 去找(www.7zhao.net欢迎您
For example, here’s the code from the Podcast.js Controller that adds a podcast after a user adds it to the system (notice how we add a high priority of 1): 欢迎访问www.7zhao.net
From there, the following things happen :
- The picks up on the task that needs to be processed
- The file is notified it has a job to do (process the incoming job)
- The database is filled with populated episodes
- The User is notified that new podcasts are available
The commands directory holds onto the code for specific Winds related tasks – it’s a simple, yet powerful CLI for the Winds API – and is especially helpful when you need to debug RSS feeds. If you’re interested, the getting started along with all of the commands are listed out .
Example output from running winds rss https://techcrunch.com/feed/ :
Tests are written with Mocha and Chai. You’re welcome to run the test suite at any time (it never hurts to find something that needs to be fixed). At this time, only Workers and API have coverage – and we’re still working on getting to the 100% mark; however, frontend coverage with jest will be coming soon!
Winds ENV ️
There are two places that require a .env ( ) file for running the application: /app/.env as well as /api/tests (assuming you are going to be writing tests). You’ll need to create a .env file inside of /app in order for the application to work. 本文来自去找www.7zhao.net
Here’s a boilerplate .env file to help you get started: 本文来自去找www.7zhao.net
Note : There are inline notes to help guide you through the setup of your .env file 欢迎访问www.7zhao.net
Running PM2 :runner:
PM2 is a process manager and we use it extensively for Winds. It’s an extremely powerful tool and we’re big fans of the project, as well as the maintainers. They are quick to respond if a bug arises, and most importantly, it works very well for what we need to do. 本文来自去找www.7zhao.net
Node.js is single threaded by design. This has its ups and downs – it’s extremely fast, but bound to a single I/O operation at a given time. Under the hood, PM2 uses the Node.js cluster module so that the scaled application’s child processes can automatically share server ports. The cluster mode allows networked Node.js applications to be scaled across all CPUs available, without any code modifications. This greatly increases the performance and reliability of the application at hand, depending on the number of CPUs available. 本文来自去找www.7zhao.net
I’d recommend learning the commands for PM2 if you are going to be developing on Winds, or if you plan on using PM2 for your own application. In all honesty, the best feature is the watch command that is built-in – it automatically watches for changes and reloads the app when necessary. Here are a few commands that I use daily :
- pm2 start process_dev.json ( Starts the processes via commands set in the process_dev.json file)
- pm2 list ( Lists all running processes)
- pm2 restart all ( Restarts all running processes managed by pm2)
- pm2 log ( Tails the logs that the various processes are spitting out)
Note : Use ctrl+c to get out of the tailing logs
Let’s Get Started :dancers:
You’ve made it this far. Congratulations! All of the dependencies are installed, repo is cloned, your .env is set up… we’re ready to go!
Create a New Branch
Inside of your working directory, create a new branch called “feature”. Here’s the code for it if you need: 欢迎访问www.7zhao.net
Now that you have the code cloned to your machine, let’s go ahead and get MongoDB up and running. You can use the following command in a separate terminal. www.7zhao.net
Note : If you’re looking for a decent GUI for MongoDB, have a look at Compass. You can download it or run brew cask install mongodb-compass .
Similarly to MongoDB, let’s go ahead and get Redis up and running. For this, I like to use the native command (from your command line): copyright www.7zhao.net
Once started, you should see the Redis logo in the terminal (as shown above). 本文来自去找www.7zhao.net
Start the Winds API & Workers
MongoDB is up and running alongside Redis. Now it’s time to start Winds. Head to the base root of the Winds directory and run the following command: 去找(www.7zhao.net欢迎您
You should see the following once the application spins up: www.7zhao.net
Let’s Start the Winds UI
With Winds, we provide two ways to start the application UI: 欢迎访问www.7zhao.net
The first method starts the application inside of an Electron wrapper :
The second option starts the application in a Chrome browser, which is much easier for debugging purposes:
Feel free to choose whichever one you like! I’ll be using the browser version as it’s easier to navigate the DOM and seems to reload faster. 欢迎访问www.7zhao.net
Woo! You’ve successfully set up and started Winds on your machine! :tada:
Adding a New Feature :bell:
We’ve covered a lot so far, but nothing concrete when it comes to adding new features to the platform. Since this is our first time showing off how to add a new feature, we’re going to keep it simple – we’ll add a social button to the frontend.
Before moving ahead with development, please create an account by selecting 3 or more interests and following the guided steps.
Don’t be alarmed when you log in. You’ll see a rather blank screen as we haven’t added any content yet.
This is easily solved with an OPML file import :grinning:. , then follow the instructions below to import it into Winds.
Click “New” > “New OPML” and a dialog will appear: 本文来自去找www.7zhao.net
Once the dialog appears, drag and drop the downloaded OPML file into the drop zone. 去找(www.7zhao.net欢迎您
Click “Add RSS”. Reload the page and you should see a list of articles! www.7zhao.net
If you’re wondering why the “Featured on Winds” and “Discover” section are empty, it’s for two reasons: 欢迎访问www.7zhao.net
- The Featured on Winds requires that a MongoDB database flag is set to true. For example, it must say “featured: true” on an RSS feed or a Podcast feed.
- The Discover recommendation feature is powered by our machine learning. Machine learning takes time, as it learns from your interactions with content. The more that you interact with your content, the better.
Note : For this tutorial, it’s not necessary to get these two components up and running. But if you want to experiment, I’d suggest jumping into MongoDB Compass and setting an RSS feed’s “featured” key to the boolean value of true. 去找(www.7zhao.net欢迎您
Starting to Code
As mentioned, we’re going to add a social button to the frontend. For the purpose of this exercise, we’ll add it to the top level RSS feeds.
First, click on the RSS section header: 去找(www.7zhao.net欢迎您
Next, have a look at each element. Notice how they are missing a Twitter logo? We’re going to add that.
Pro Tip : The easiest way to find what you’re looking for is to find the class name and then search for it in your editor.
For this component, we’re going to be looking for two classes – “far fa-bookmark”. You can search for this in your editor, or you can simply go to “app/src/components/ArticleListItem.js” – line number 57. www.7zhao.net
First, we need to include a module called is-electron. This module ensures that we’re only showing an icon (and using functionality) in the web environment. The package is already installed, you just need to add it to the imports at the top of the file like so:
Between the following <span> ’s on line 59 and line 60, we’re going to add our Twitter button! 去找(www.7zhao.net欢迎您
After adding the code snippet above, your code should look like this: 本文来自去找www.7zhao.net
We’re calling the function tweet() , so we’ll want to make sure we create that as well. Just before the render method, create a new method called “tweet”. You can copy and paste the following code:
Now, try clicking on the Twitter logo in the UI. If all went well, you should see a Tweet dialog open with the title of the article, along side the URL with the hashtag Winds!
Woo! You created your first feature on Winds – hopefully, one of many! Time to celebrate! 欢迎访问www.7zhao.net
If you’re still a little fuzzy on the process, run git stash and try it all over again. It doesn’t hurt to do things more than once :wink: www.7zhao.net
Feeling like you have everything down? Let’s see some code! Here are a few ideas that may help you get started:
- Facebook Like Buttons
- Bookmark Support
- Dark mode to support macOS Mojave
- Likes (our API already provides support for them)
- General CSS cleanup
- Test coverage for the API and Workers
Note : We’re also hiring a Full-time (contract) developer to join the team to work on Winds. Think you have what it takes? Ping me with your LinkedIn profile and any examples of coding work that you’ve worked on as the sole contributor.
is the most popular application of its type – and we couldn’t be more excited. Free desktop applications are available for macOS, Linux, and Windows, and a web version is available as well. The application features several pieces of functionality, notably feeds and personalized content recommendations, all of which are powered by , the leader in API based news feeds, activity streams, and personalization as a service. 内容来自www.7zhao.net
Thank you for sticking around and learning a bit about Winds! We hope to see some PRs from you in the near future!
Happy Coding !
以上为Winds – An in Depth Tutorial on Making Your First Contribution to Open-Source Software文章的全部内容，若您也有好的文章，欢迎与我们分享！ 去找(www.7zhao.net欢迎您