Blog post - connecting contributors with projects #730
Conversation
There was a problem hiding this comment.
First off, sorry that it took me so long to get around to reviewing this (crazy busy recently).
This looks really great to me @MichaelViveros!
Other than a few little rewordings here and there (commented inline), all I'd ask is that you update the name of the file to correspond with today's date. Would be cool to push the merge button and make some noise about this today 😊
|
|
||
| ## Introduction | ||
|
|
||
| One problem with open-source software is that it can be difficult to find a project to contribute to and actually get started contributing to it. Some open-source projects can seem very intimidating to newcomers since they have a very large code base and minimal documentation about how to get involved with the project. Other projects are are better and have: |
There was a problem hiding this comment.
"Other projects are are better and have:" -> "Other projects make it easier for prospective contributors to localize and figure out how to participate in a project, having for example:"
|
|
||
| ## Contributing Info | ||
| ### How it Works | ||
| As mentioned above, Contributing Info corresponds to 3 pieces of information, some of which are auto-populated when Scaladex is indexed, and all of which can be manually set by a project maintainer in their project's edit page in Scaladex: |
There was a problem hiding this comment.
"As mentioned above, Contributing Info corresponds to 3 pieces of information, some of which are auto-populated when Scaladex is indexed, and all of which can be manually set by a project maintainer in their project's edit page in Scaladex:" -> "To Scaladex, Contributing Info consists of the three pieces of information mentioned above: a contributor's guide, a collection of beginner-friendly issues, and a link to a gitter chatroom for the project where newcomers can come to easily ask questions. And perhaps most importantly; Scaladex can automatically obtain much of this info for your project! It's also possible for a project maintainer to automatically set this information on their project's edit page in Scaladex."
There was a problem hiding this comment.
Should I get rid of the list below describing how each piece of contributing info can be set? It doesn't fit well with what you added, maybe just adding a connecting sentence like "Here's how each piece of contributing info can be set:" will make it fit better.
I liked that list since it tells maintainers specifically how each piece of contributing info is set/auto-populated.
There was a problem hiding this comment.
Nah, keep the list. It sometimes helps to be a bit repetitive in blog articles; people tend to skim 😉
|
|
||
| Scaladex uses Github's [GraphQL API](https://developer.github.com/v4/) to get a project's beginner-friendly issues, see the [Github Topics](#github-topics) section below for more info about Github's GraphQL API. To get a project's contributing guide, Scaladex uses Github's [REST API](https://developer.github.com/v3/) to send a GET request to the [Community Profile API](https://developer.github.com/v3/repos/community/) which will return links to a project's contributing guide, code of conduct and license. Lastly, to get a project's chatroom, Scaladex generates a URL for a project's gitter room like <https://gitter.im/scalacenter/scaladex> and checks if that URL exists. | ||
|
|
||
| The front page of Scaladex has a section which highlights projects that have Contributing Info and it picks a random selection of projects each time the page is loaded to give the same amount of exposure to all projects with Contributing Info. |
There was a problem hiding this comment.
"The front page of Scaladex has a section which highlights projects that have Contributing Info and it picks a random selection of projects each time the page is loaded to give the same amount of exposure to all projects with Contributing Info." -> "You can also find Contributing Info on the front page of Scaladex. Now, Scaladex highlights a random subset of projects which have Contributing Info on the front page of Scaladex. It picks a random selection of projects each time the page is loaded to give the same amount of exposure to all projects with Contributing Info. We hope to highlight and better guide potential contributors to projects and issues that are of interest to them!"
|
|
||
| With Github's REST API, you have to make multiple requests to different routes to get project info about multiple projects. And when you make a request, all the data related to that request would be returned. For example, if you wanted to get the most recent 3 issues created for 5 projects, you would make 5 requests to 5 different routes for each project. Each request would return all the project’s issues. With the GraphQL API, all requests are made to the same route and in the body of the request you input a GraphQL query which specifies exactly what information you want and for which projects. So for the example above of getting the most recent 3 issues created for 5 projects, you would make 1 request to 1 route containing a query to get only the 3 most recent issues for the 5 projects and only those 3 issues for each of the projects would be returned. This results in less requests to Github’s API and less data returned in each response. | ||
|
|
||
| So I replaced keywords with topics for projects in Scaladex and used Github’s new GraphQL API to fetch the topics. These topics are fetched for all projects when the server is indexed. A lot more projects have topics than keywords (which had to manually be set by maintainers in Scaladex), so this greatly improved the ability to search for projects based on categories in Scaladex since there are a lot more projects with categories. |
There was a problem hiding this comment.
🎉 (I'm still jazzed about this 😊 )
|
@heathermiller Thanks for the feedback, should be good to go now |
|
Looks good to me now! Thanks and congrats @MichaelViveros! 🎉 🎉 |
@heathermiller Blog post for my GSOC 2017 Project