Skip to content

Latest commit

 

History

History
234 lines (156 loc) · 8.62 KB

CONTRIBUTING.md

File metadata and controls

234 lines (156 loc) · 8.62 KB
Raw

Contributing to Ember Blog

New contributors are welcome! Ember Blog is maintained by an all-volunteer team, and we are thankful for your help.

You can support us in a few different ways:

  • Suggest an article for The Ember Times
  • Do a write-up of an article for The Ember Times
  • Complete an issue with the label "good first issue" or "help wanted"
  • Open an issue to provide feedback

If you have questions or need help with writing, please visit the #dev-ember-learning channel on the Ember Community Discord.

Setup

Installation

  1. Fork and clone this repo.

    git clone [email protected]:<your GitHub handle>/ember-blog.git

  2. Change directory.

    cd ember-blog

  3. Install packages.

    npm install
Creating a blog post

  1. We use Markdown when writing a blog post.

  2. The file must be saved in the content directory.

    # Create an Ember Times blog post for August 29, 2020
touch content/the-ember-times-issue-162.md

  3. We use alex and markdownlint for linting. If your branch's CI (continuous integration) didn't pass these linters, please consider rewording or updating Markdown syntax to fix the error. If the linter incorrectly marked something as an error, you may add an exception to your file.

  • If GitHub Actions lint CI fails on alex, the failure is usually listed far above Exit status 1.
⚠ 1 warning
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] lint:alex: `alex {content,post-templates}/**/*.md`
npm ERR! Exit status 1

Search for "warning" to see the specific alex failure, which will look like:

content/the-ember-times-issue-173.md
  71:8-71:12  warning  Don’t use `Tang`, it’s profane  tang  retext-profanities
  • If GitHub Actions lint CI fails on markdownlint, the failure is usually listed closely above Exit status 1. In the example below, the markdownlint error is MD034. Full list of rules can be found here.
content/the-ember-times-issue-173.md:39:16 MD034/no-bare-urls Bare URL used [Context: "https://dev.to/jelhan/format-g..."]
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] lint:md: `markdownlint {content,post-templates}/**/*.md`
npm ERR! Exit status 1
Running app locally (optional)

  1. You can preview how the blog post looks by running the Ember app locally.

    ember serve

  2. Visit http://localhost:4200.

Writing for The Ember Times

Thank you for contributing to The Ember Times! Let us know if you can be a guest or regular writer. On Discord, you can reach the team in the #support-ember-times channel.

Claiming a news item

  1. Where can you find news items that you can cover? Look for an in-progress pull request with the label Ember Times.

  2. You can claim a news item by leaving a comment in the pull request. If you have edit permission for the pull request, you can update the description by adding the lock emoji 🔏 and your GitHub handle:

    - [x] Ember v3.22 released (🔏 @tomster)
- [ ] How to use GraphQL with Ember (🔏 @zoey) <-- claimed!
- [ ] 16th edition of I Contribute to Ember
Updating the blog post

  1. After installing the repo (see Setup), you will need to perform a few extra steps to work from the correct branch.

    # Set upstream (one-time operation)
git remote add upstream https://github.com/ember-learn/ember-blog

# Get branches and commits from upstream
git fetch upstream

# Switch to the current Ember Times branch
git switch -t upstream/blog/embertimes-165 # or, git checkout blog/embertimes-165

  2. Open the Markdown file for the current blog issue: content/the-ember-times-issue-165.md.

  3. Add your name, introductory line, and writing to the Markdown file. You'll see useful notes and placeholders in the file.

    ## [Section title in sentence case 🐹](section-url)

<change section title emoji>
<consider adding some bold to your paragraph>
<please include link to external article/repo/etc in paragraph / body text, not just header title above>

<add your name to author list, top and bottom>
<add blurb and emoji to "SOME-INTRO-HERE">

  4. When you're finished with writing, create a pull request. Let the team know on Discord that it is ready for review!

    # Commit changes
git add .
git commit -m 'Covered the article "How to use GraphQL with Ember"'

# Push changes
git push origin blog/embertimes-165

# Create a pull request from your repo on GitHub

  5. Note: If you are making a Handlebars code block, you must use handlebars instead of hbs. For example:

{{!-- app/templates/application.hbs --}}
<h1>Hello world!</h1>
{{outlet}}
Meeting the deadline

  1. Friday afternoon is a general deadline that the team strives to meet. We encourage you to turn in your writing early to get effective feedback and revise as much as needed.

  2. We fully understand that you may be busy and need to miss writing. If so, we encourage you to let your team know.

Publishing an Issue of The Ember Times

Substack instructions
  1. Get a login to the Ember Times account on Substack from #support-ember-times.
  2. Merge the blog post PR to the main branch.
  3. Draft a new post in Substack. From https://github.com/ember-learn/ember-blog/find/main, search for the issue number, e.g. "171".
  4. Put greeting e.g. "👋 Emberistas! 🐹" and the intro AKA summary of articles in the Substack subtitle. No need to repeat in the content of the Substack itself.
  5. Copy the copy content of the blog below the "intro" from there into Substack.
  6. You may need to manually import images such as Office Hours Tomster mascot https://github.com/ember-learn/ember-blog/blob/main/public/images/tomsters/officehours.png.
  7. Also in Substack "Post settings", you may want to remove "👋 Emberistas!" so that the social preview is "🐹 " as we are limited on space.
  8. Send yourself a test email to preview how it looks.
  9. Ensure the author for the issue in substack is set to The Ember Times and not your personal substack account (you can find this setting near the top of a draft just under subtitles).
  10. Send to the list!
Twitter instructions
  1. Post tweet on Tweetdeck to post on Monday (second day of #engagement)
  2. Set $natural reminder on Discord, for example: $natural on February 15th at 2:00pm send post tweet 2 news & announce @Alon (if you're avail!) :newspaper2: to #support-ember-times-staff
  3. Use one emoji for each line item as a bullet point
  4. Try to @ or hashtag when appropriate
  5. Include the URL to the blog
dev.to instructions
  1. Copy raw from GitHub, delete top YAML portion.
  2. If they appear in the preview, delete any alex-ignore or markdownlint-ignore.
  3. Double curlies {{ in header link titles will sometimes give you a liquid error. For example, with this heading [No Implicit This or {{foo}} to {{this.foo}} Codemod](https://github.com/ember-codemods/ember-no-implicit-this-codemod) I just deleted the double curlies to fix.
  4. Check for weird line breaking. We can fix this with stricter markdownlint but it was a bit cumbersome for blog writers!
  5. Add canonical URL and series name (The Ember Times should come up)
  6. Add body image for Readers' Questions image manually https://github.com/ember-learn/ember-website/blob/main/public/images/tomsters/officehours.png.
  7. Format manually if needed.

Upgrading dependencies

If you are helping to update this app's dependencies, here are some things you may need to know.

Things to check manually

In the deploy preview, check the "View source" on the page. Does it have the full HTML? If not, it indicates that there may be an issue with Fastboot.