Added "Contribute" page with active issues. #1126

Open
wants to merge 3 commits into
from

Projects

None yet

5 participants

@hpierce1102
hpierce1102 commented Jan 7, 2017 edited

Issue: #1099

The links to AST-Explorer and the handbook are included in the CONTRIBUTING.md content, Though maybe they deserve their own callouts?

Maybe this shouldn't be part of the top level nav, but inside the docs menu?

babel-contributing

@hzoo
Member
hzoo commented Jan 7, 2017

so awesome! thanks for "contributing" this @hpierce1102 (heh)!

I wanted to revamp the contributing anyway so it's ok

scripts/contributing.js
+/* global jQuery*/
+
+(function($){
+ var githubIssuesEndpoint = 'https://api.github.com/repos/babel/babel/issues';
@hzoo
hzoo Jan 7, 2017 Member

May not have to be in this pr but we could actually link up issues in other repos too

babel/x such as babili, babel-preset-env, babylon, etc

@hpierce1102
hpierce1102 Jan 8, 2017

I initially didn't include them because I wanted to know how well this would be received and I was a bit worried about sending too large of a PR.

I'll add issues for more repos over the next day over the next day or so.

@xtuc
xtuc Jan 8, 2017 Member

Note that:

This endpoint may also return pull requests in the response. If an issue is a pull request, the object will include a pull_request key.

I don't know if we want PR there.

@xtuc
xtuc Jan 8, 2017 Member

Do you know if there quotas on API calls?

@hpierce1102
hpierce1102 Jan 8, 2017

Note that: ... I don't know if we want PR there.

Yeeeeeeep. That was an oversight. I even made a note to check for that. I'll address that in a future commit.

Do you know if there quotas on API calls?

Great question. After looking into it there's a 60 request/hour/IP limit for unauthenticated requests according to the Github docs. There's a caching header on the response of 60 seconds, so theoretically we could do a single call as much as we want. Since I've used 2 here, there's a possible issue if someone were to refresh every minute for long enough, but that doesn't seem practical. During my testing, I wasn't able to use more than 20/hour.

I guess I don't see this as a practical enough issue as is - though this might be a reason to split up repos across multiple pages rather than aggregating all issues for all repos on the one page.

@xtuc
xtuc Jan 8, 2017 Member

Ok, seems ok.

@xtuc
xtuc Jan 11, 2017 Member

It seems possible to query for issues in an entier org:

GET /orgs/:org/issues

@hpierce1102
hpierce1102 Jan 17, 2017

The docs mention authentication for that endpoint - and I'm getting a 404 when trying to access it (despite expecting a 401):

https://api.github.com/orgs/babel/issues

@DrewML
DrewML Jan 17, 2017 edited Member

I get a 404 for that endpoint even when using an API key with auth for our org 🤔. Same with my other repositories. May just be broken.

@hzoo
Member
hzoo commented Jan 7, 2017

Not sure yet but maybe we should move contributing.md to the website and just link to it. Maybe the open issues can be put front and center (or we make another separate page as well)?

@hpierce1102

I like the idea of linking from babel/babel to the website for this kind information. If I understand correctly (and I may not, this is my first experience using Jekyll), that would give us more control over how this information is presented.

For instance, I see a picture a decent layout keeping the "Setup | Running linting/tests | Writing tests | Internals" and "Before contributing, please read our code of conduct." sections above the fold with active issues following.

I'll add another commit to this addressing those points.

@hpierce1102 hpierce1102 Entire issue is now clickable.
Embedded contributing.md instead of including it.
Moved issues to a more prominent position.
64cf3c9
@xtuc

👍 This looks great, thanks for your PR.

scripts/contributing.js
+/* global jQuery*/
+
+(function($){
+ var githubIssuesEndpoint = 'https://api.github.com/repos/babel/babel/issues';
@xtuc
xtuc Jan 8, 2017 Member

Note that:

This endpoint may also return pull requests in the response. If an issue is a pull request, the object will include a pull_request key.

I don't know if we want PR there.

@xtuc
xtuc Jan 8, 2017 Member

Do you know if there quotas on API calls?

scripts/contributing.js
+ },
+ success : function(data){
+ for(var i = 0; i < data.length; i++){
+ $('.beginnerFriendlyIssues').append('<li><a href="' + data[i].html_url + '"><span class="issueNumber">#' + data[i].number +'</span></a><span>' + data[i].title + '</span></li>');
@xtuc
xtuc Jan 8, 2017 edited Member

Do you mind if the entier text is clickable?

+ throw error;
+ }
+ }
+ );
@xtuc
xtuc Jan 8, 2017 Member

We could use one single call for both labels.

https://api.github.com/repos/babel/babel/issues?labels=beginner-friendly,help%20wanted

labels (string): A list of comma separated label names. Example: bug,ui

@hpierce1102
hpierce1102 Jan 8, 2017

Using more than one label seems to restrict the query more by only including issues with both "beginner-friendly" and "help wanted". So that url only provides 2 issues while this url:

https://api.github.com/repos/babel/babel/issues?labels=help%20wanted

provides 9 issues.

I don't think we'll be able to combine these.

@xtuc
xtuc Jan 8, 2017 Member

Yes, that's right.

_data/navigation.yml
@@ -32,3 +32,5 @@
url: /blog/
- title: FAQ
url: /docs/faq
+- title: Contribute
+ url: /docs/contributing
@xtuc
xtuc Jan 8, 2017 Member

There is an issue for detecting the currently active item in the menu.

I will take a look, I think @existentialism already mentionned it.

i

@hpierce1102

Few changes:

  • Embedded CONTRIBUTING.md in order to move open issues up to a more prominent position.

  • Removed the "NOTE: DO NOT OPEN..." - I don't think it makes sense in the context of the website personally (open to feedback).

  • Made entire issue text clickable.

babel-contributing2

docs/contributing.md
@@ -7,7 +7,23 @@ custom_js_with_timestamps:
- contributing.js
---
-{% include babel/CONTRIBUTING.md %}
@xtuc
xtuc Jan 8, 2017 edited Member

I would prefer keeping the documentation in Babel/babel repo.

Edit: We could maybe split the CONTRIBUTING into parts to reduce its size.

@hzoo hzoo referenced this pull request in babel/babel-preset-env Jan 9, 2017
Closed

modules/es7.array.includes.js -> modules/es7.array.includes #129

4 of 4 tasks complete
@hpierce1102 hpierce1102 Added other repos.
Linked contributing docs over embedding them.
055c04d
@hpierce1102

babel-contributing3

I couldn't figure out this bit - multiple tabs are highlighted on the babel-preset-env page. I suspect it's the same issue as the docs being highlighted incorrectly as was mentioned earlier.

@existentialism
Member

@hpierce1102 yeah, the website is currently using:

{% if page.url contains item.url%}

to highlight the current section and anything underneath it.

Since we're treating contributing as a top level nav item in the bar, let's place it at the root (./contributing/ vs ./docs/contributing)?

@existentialism
Member

Aligning both the issue number boxes and the edge of the text helps scan-/read-ability:

image

@xtuc
Member
xtuc commented Jan 17, 2017

This looks awesome!

@existentialism I think It would looks even prettier with the text centered in the yellow boxes.

@hpierce1102 I think we could add a fallback link to Babel's issue tracker in case the Github API limit is exceeded.

The limit isn't that high, it's IP based, in France some users from the same ISP can share the same IP address. It would be bad If people coudn't contribute to Babel because of this :)

@xtuc
Member
xtuc commented Jan 17, 2017

highlighting Issue in at #1141

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment