fix: Updating How To Contribute Guide

[CBID2]

Proposed Changes

On July 31, 2023, @abbycabs asked me & @UlisesGascon to make updates to the "How To Contribute to Open Source" section of the open source guide. This PR will add more links to specific examples of open source contributions mentioned in the guide. These additions will aid people, especially those who are new to open source, gain a better idea of how and the benefits of contributing these projects.

Note to Reviewers

This PR is still a work in progress.

• Have you followed the contributing guidelines?
• Have you explained what your changes do, and why they add value to the Guides?

Please note: we will close your PR without comment if you do not check the boxes above and provide ALL requested information.

---

[CBID2]

.gitignore

@@ -7,5 +7,5 @@ bin node_modules /vendor Gemfile.lock

css/main.scss .asset-downloads 2 changes: 1 addition & 1 deletion 2 _articles/en-US/metrics.md

@@ -23,7 +23,7 @@ With more information, you can:

• Figure out where new users come from
• Identify, and decide whether to support, an outlier use case or functionality
• Quantify your project's popularity
• Raise money through sponsorships
• Raise money through sponsorships and grants

For example, Homebrew finds that Google Analytics helps them prioritize work:

4 changes: 2 additions & 2 deletions 4 _includes/footer.html

@@ -4,7 +4,7 @@

<img src="{{ "/assets/images/illos/squirrel.svg" | relative_url }}" class="little-illo mb-3" alt="squirrel illustration">

{{ site.data.locale[site.locale].footer.contribute.heading }}

{{ site.data.locale[site.locale].footer.contribute.description }}

@@ -19,7 +19,7 @@

{{ site.data.locale[site.locale].footer.contribute.headi

<img src="{{ "/assets/images/illos/bird.svg" | relative_url }}" class="little-illo mb-3" alt="bird illustration">

{{ site.data.locale[site.locale].footer.subscribe.heading }}

          <div class="mc-field-group col-12">

4 changes: 2 additions & 2 deletions 4 _includes/head.html

@@ -2,10 +2,10 @@

<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.2.4/jquery.min.js"></script> <script src="{{ "/js/script.js" | prepend: site.baseurl }}"></script> <script src="{{ "/js/script.js" | relative_url }}"></script> <script> (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), 2 changes: 1 addition & 1 deletion 2 [_includes/search-result.html](https://github.com/[/pull/3098](https://github.com//pull/3098)#diff-bc17b142a0a0b0a6135c19f1e2f70cb47e40acc44ea58819b90231b1d6ef34d7)

@@ -1,6 +1,6 @@

[ {{ include.article.title }} ]({{ include.article.url | relative_url }})

2 changes: 1 addition & 1 deletion 2 _layouts/default.html
@@ -7,7 +7,7 @@ {{ content }}

<script src="{{ site.baseurl }}/js/vendor/anchor-js/anchor.min.js"></script> <script src="{{ "/js/vendor/anchor-js/anchor.min.js" | relative_url }}"></script> <script> var selector = '#content h2, #content h3, #content h4, #content h5'; 2 changes: 1 addition & 1 deletion 2 [assets/css/custom.scss](https://github.com//pull/3098#diff-0cc42738c953218500f377a0ee933c7511a34b0cb7eadbe4a6c156b3ee59e64b) @@ -7,7 +7,7 @@ img { } blockquote { font-style: italic; color: $gray; border-left: $border; border-width: 4px; padding: $spacer-1 0 0 $spacer-2; 4 changes: 2 additions & 2 deletions 4 [docs/roadmap.md](https://github.com//pull/3098#diff-6a17656d764b8e1930354f341cf7f47960b63845c3046edcd8bbf282aaa2f464) @@ -2,7 +2,7 @@ Our vision for Open Source Guides is to provide a jumping off point for individuals, communities, and companies to sustainably embrace open source. ### H1 2017 ### Q1 2017 We started by focusing on open source creators, because they play a critical role in growing healthy projects. Creators help set good examples for contributors and consumers of open source. We also noticed there were very few comprehensive resources aimed at helping creators. @@ -11,7 +11,7 @@ We started by focusing on open source creators, because they play a critical rol * [x] Expand [Contributing to Open Source on GitHub](https://guides.github.com/activities/contributing-to-open-source/) to include community best practices for contributors, and move it to Open Source Guides * [ ] Foster healthy community dynamics so the guides become a place to codify community best practices ### H2 2017 ### Q2 2017 We'll improve upon existing content and start to focus on additional content for open source consumers and contributors. 2 changes: 1 addition & 1 deletion 2 [index.html](https://github.com//pull/3098#diff-0eb547304658805aad788d320f10bf1f292797b5e6d745a3bf617584da017051) @@ -20,7 +20,7 @@ # {{ site.title }} {% assign articles = site.articles | where: 'locale', site.locale | sort: 'order' %} {% for article in articles %} [ ]({{ site.baseurl }}{{ article.url }})[ ```

``` ]({{ article.url | relative_url }}) 4 changes: 2 additions & 2 deletions 4 [js/search.js](https://github.com//pull/3098#diff-fdb1e09e7a1b99e9f2359b2319cbb2a5e61c9610a9b8e01e352b522493445490) @@ -5,7 +5,7 @@ layout: (function() { var searchWorker; var searchURL = "{{ "/search/" | prepend: site.baseurl }}"; var searchURL = "{{ "/search/" | relative_url }}"; var replaceState = false; var replaceStateTimeout; var searchBox = document.getElementById('search-box'); @@ -35,7 +35,7 @@ function search(searchTerm) { searchBox.setAttribute("value", searchTerm); if(!searchWorker) { searchWorker = new Worker("{{ "/js/search_worker.js" | prepend: site.baseurl }}"); searchWorker = new Worker("{{ "/js/search_worker.js" | relative_url }}"); ``` searchWorker.addEventListener("message", function(e) { displaySearchResults(e.data); ``` 2 changes: 1 addition & 1 deletion 2 [js/search_worker.js](https://github.com//pull/3098#diff-ff6eeae96f81a97f6fd1d80662f9cf4225c66de2a9ec621c0d55a00e66e5f6de) ## @@ -3,7 +3,7 @@ layout: // http://jekyll.tips/jekyll-casts/jekyll-search-using-lunr-js/ importScripts("{{ "/js/lunr.min.js" | prepend: site.baseurl }}"); importScripts("{{ "/js/lunr.min.js" | relative_url }}"); var store = { {% for article in site.articles %} 7 changes: 7 additions & 0 deletions 7 [package.json](https://github.com//pull/3098#diff-7ae45ad102eab3b6d7e7896acd08c427a9b25b346470d7bc6507b6481575d519) @@ -6,9 +6,14 @@ }, "devDependencies": { "async": "^2.0.0", "download": "^5.0.3", "ebrew": "^0.1.1", "fastmatter": "^1.1.1", "glob": "^7.0.5", "ignore": "^3.1.3", "js-yaml": "^3.6.1", "kindlegen": "^1.1.0", "mkdirp": "^0.5.1", "remark-lint": "^5.0.0", "remark-parse": "^2.0.0", "remark-retext": "^2.0.0", @@ -21,8 +26,10 @@ "retext-sentence-spacing": "^1.0.0", "retext-simplify": "^3.0.0", "retext-words": "bkeepers/retext-words", "slug": "^0.9.1", "to-vfile": "^2.1.0", "unified": "^5.0.0", "unist-util-visit": "^1.1.1", "vfile-reporter": "^3.0.0", "vfile-statistics": "^1.0.0" }, 196 changes: 196 additions & 0 deletions 196 [script/ebooks](https://github.com//pull/3098#diff-a4e23439661bd7af7948c6ec14cdb00c069715330b4f469a5e5536b7c229c8a5) @@ -0,0 +1,196 @@ #!/usr/bin/env node // Generate EPUB and MOBI ebooks const fs = require('fs'); const path = require('path'); const exec = require('child_process').exec; const fastmatter = require('fastmatter'); const mkdirp = require('mkdirp'); const slug = require('slug'); const unified = require('unified'); const parse = require('remark-parse'); const stringify = require('remark-stringify'); const visit = require('unist-util-visit'); const download = require('download'); const ebrew = require('ebrew'); const processor = unified() .use(parse) .use(replaceAsides) .use(replaceCheckboxes) .use(fixImages) .use(downloadImages) .use(stringify); buildBooks([ '_articles/how-to-contribute.md', '_articles/starting-a-project.md', '_articles/finding-users.md', '_articles/building-community.md', '_articles/best-practices.md', '_articles/leadership-and-governance.md', '_articles/getting-paid.md', '_articles/code-of-conduct.md', '_articles/metrics.md', '_articles/legal.md', ]); function buildBooks(files) { const out = 'assets/ebooks/open-source-guide'; const tempFile = '_ebook.md'; mkdirp.sync('assets/ebooks'); mkdirp.sync('.asset-downloads'); let source = files.map(readFile).join('\n\n'); const { text, promises } = downloadImages(source); fs.writeFileSync(tempFile, text); promises .then(() => markdownToEpub(tempFile, `${out}.epub`)) .then(() => epubToMobi(`${out}.epub`, `${out}.mobi`)) .then(() => fs.unlinkSync(tempFile)) .catch(err => console.error(err)); } function readFile(file) { const md = fs.readFileSync(file, 'utf8'); // Replace frontmatter with chapter title const { attributes, body } = fastmatter(md); let text = `# ${attributes.title}\n\n${body}`; return processor.process(text).contents; } function markdownToEpub(mdFile, epubFile) { return new Promise((resolve, reject) => { console.log(`Building ${epubFile}...`); ``` const manifestFile = '_ebook.json'; fs.writeFileSync(manifestFile, JSON.stringify({ tocDepth: 1, title: 'Open Source Guides', subtitle: 'Open source software is made by people just like you. Learn how to launch and grow your project.', author: 'GitHub', publisher: 'GitHub', rights: 'CC-BY-4.0', date: (new Date()).toISOString().slice(0, 10), contents: path.resolve(mdFile), })); ebrew.generate(manifestFile, epubFile, err => { fs.unlinkSync(manifestFile); if (err) { reject(err.stack || err); } else { resolve(); } }); ``` }); } function epubToMobi(epubFile, mobiFile) { return new Promise((resolve, reject) => { console.log(`Building ${mobiFile}...`); ``` const kindlegen = require.resolve('kindlegen/bin/kindlegen'); exec(`${kindlegen} ${epubFile} -c2 -verbose -o ${path.basename(mobiFile)}`, (err, stdout) => { if (err && stdout.includes('MOBI file could not be generated because of errors!')) { reject(stdout); } else { resolve(); } }); ``` }); } function downloadImages(text) { function image(processor) { return ast => visit(ast, 'image', node => { if (node.url.startsWith('http')) { const url = node.url; const filename = slug(path.basename(node.url)); const filepath = `./.asset-downloads/${filename}.jpg` node.url = filepath; if (fs.existsSync(filepath)) { promises.push(Promise.resolve()); } else { const promise = download(url) .then(data => { fs.writeFileSync(filepath, data); }); promises.push(promise); } } }); } let promises = []; const processor = unified() .use(parse) .use(image) .use(stringify); text = processor.process(text).contents; return { promises: Promise.all(promises), text, }; } /* Replace asides with Markdown blockquotes:  I fumbled it. I didn't put in the effort to come up with a complete solution. Instead of an half-assed solution, I wish I had said "I don't have time for this right now, but I'll add it to the long term nice-to-have list." — @lord, ["Tips for new open source maintainers"](https://lord.io/blog/2014/oss-tips/) */ function replaceAsides(processor) { return ast => visit(ast, 'html', node => { if (node.value.startsWith(']*>/, '\n') .replace(/\(\/assets\//, '(./assets/') .replace(/<\/?(aside|p).*?>/g, '') .trim() .replace(/(^|\n) */g, '\n> '); } }); } /* Replace checkboxes with unordered lists: Does it have a license? Usually, this is a file called LICENSE in the root of the repository. */ function replaceCheckboxes(processor) { return ast => visit(ast, 'html', node => { if (node.value.startsWith('/g, '') .trim() .replace(/^/, '* '); } }); } /* 1. Remove image alts, otherwise they will be visible in a book 2. Fix asset paths */ function fixImages(processor) { return ast => visit(ast, 'image', node => { node.alt = null; node.url = node.url.replace(/^/assets//, './assets/'); }); }

@karasowles, I think some of these comments are spammy

[olsza]

refactoring - removed trailing whitespace

[olsza]

@CBID2 Back to the topic in the comment #3094 (comment)
I have not been able to reproduce such a bug on your branch.

Maybe it was caused by a cache in GitHub, on another project I had similar problems with tests failing, but I just restarted the action in GitHub and it worked fine the second time, maybe it will work here too....
I did a bit of refactoring on your code ;) when you try to merge again, maybe the error will not occur.

[CBID2]

@CBID2 Back to the topic in the comment #3094 (comment)

I have not been able to reproduce such a bug on your branch.

Maybe it was caused by a cache in GitHub, on another project I had similar problems with tests failing, but I just restarted the action in GitHub and it worked fine the second time, maybe it will work here too....

I did a bit of refactoring on your code ;) when you try to merge again, maybe the error will not occur.

Thanks @olsza! :) Could this error be from the spammy messages above? 🤔

[olsza]

@CBID2 Back to the topic in the comment #3094 (comment)
I have not been able to reproduce such a bug on your branch.
Maybe it was caused by a cache in GitHub, on another project I had similar problems with tests failing, but I just restarted the action in GitHub and it worked fine the second time, maybe it will work here too....
I did a bit of refactoring on your code ;) when you try to merge again, maybe the error will not occur.

Thanks @olsza! :) Could this error be from the spammy messages above? 🤔

Theoretically not, but maybe there is a bug in GitHub....
but I'm still investigating a hint related to the "https://libraries.io/search?platforms=NPM" link in the NL translation file, because in the test error report this occurs

[olsza]

@CBID2 Back to the topic in the comment #3094 (comment)
I have not been able to reproduce such a bug on your branch.
Maybe it was caused by a cache in GitHub, on another project I had similar problems with tests failing, but I just restarted the action in GitHub and it worked fine the second time, maybe it will work here too....
I did a bit of refactoring on your code ;) when you try to merge again, maybe the error will not occur.

Thanks @olsza! :) Could this error be from the spammy messages above? 🤔

Theoretically not, but maybe there is a bug in GitHub.... but I'm still investigating a hint related to the "https://libraries.io/search?platforms=NPM" link in the NL translation file, because in the test error report this occurs

Ok @CBID2, it's not you that's wrong, this report in the tests "says" that the link https://libraries.io/search?platforms=NPM returns 403
and in fact, if you click on the link on https://libraries.io and then copy their link and try to go directly to their sub pages, you will not get in because you have a 403 :/
It's the fault of this portal, they don't allow links to subpages :/

In the PR history of this project, I can see that there have been situations where there was a 403 error in the tests and such PRs were merged.

[CBID2]

@CBID2 Back to the topic in the comment #3094 (comment)
I have not been able to reproduce such a bug on your branch.
Maybe it was caused by a cache in GitHub, on another project I had similar problems with tests failing, but I just restarted the action in GitHub and it worked fine the second time, maybe it will work here too....
I did a bit of refactoring on your code ;) when you try to merge again, maybe the error will not occur.

Thanks @olsza! :) Could this error be from the spammy messages above? 🤔

Theoretically not, but maybe there is a bug in GitHub.... but I'm still investigating a hint related to the "https://libraries.io/search?platforms=NPM" link in the NL translation file, because in the test error report this occurs

Ok @CBID2, it's not you that's wrong, this report in the tests "says" that the link https://libraries.io/search?platforms=NPM returns 403 and in fact, if you click on the link on https://libraries.io and then copy their link and try to go directly to their sub pages, you will not get in because you have a 403 :/ It's the fault of this portal, they don't allow links to subpages :/

In the PR history of this project, I can see that there have been situations where there was a 403 error in the tests and such PRs were merged.

Thanks for clarifying this @olsza! :)