Skip to content
This repository has been archived by the owner on Mar 26, 2023. It is now read-only.
/ .github Public archive

Latest commit

 

History

History
170 lines (108 loc) · 8.39 KB

CONTRIBUTING.md

File metadata and controls

170 lines (108 loc) · 8.39 KB

Contributing to Swift Weekly Brief

Contributions are welcome and encouraged!

Please review and abide by our code of conduct.

You should have a good understanding of how Jekyll and GitHub-Pages work — or be willing to learn. 😄 We are happy to help you with any questions, just ask.

Suggestions: Have something you want to share in the newsletter? Please find the current issue notes and add a comment. Or you can open an issue or submit a pull request to the current draft with a link and description.

Fixes: Spelling, grammar, or code. Please open an issue or submit a pull request!

⚙️ Setup and process

  1. Add yourself to _data/authors.yml, if you haven't already. Please provide:
    • A username to reference for the site
    • Your name
    • GitHub username
    • Twitter username
  2. Run the new_draft.sh script to generate an issue template in _drafts/. See the example below.
  3. Open an issue on GitHub. Set the title to the newsletter issue number and date. Example: [100] Issue #100 - Jan 04, 2018
  4. Assign it to yourself.
  5. Add the current issue and full issue notes labels.
  6. We use this throughout the week to collect notes and make it easy for external contributors to contribute content. We also use this issue to collaborate with the other Swift Weekly writers and troubleshoot any problems that come up.
  7. Write the issue in _drafts/ throughout the week. We recommend writing a little each day to make it easier.
  8. For style and content, see the guide below. Also, follow the example set by previous issues.
  9. For code snippets, use jekyll highlight blocks:
{% highlight swift %} 

// swift code here

{% endhighlight %}

💡 Note: See the handy tips below!

Generating a draft

Example:

# usage: ./new_draft.sh <DATE (YYYY-MM-dd)> <ISSUE #> <AUTHOR>

$ ./new_draft.sh 2016-04-21 19 jsq  

# creates _drafts/2016-04-21-issue-19.md

Generating a GitHub issue

To generate a GitHub access token, see the GitHub docs.

Example:

# usage: export SWIFTWEEKLY_TOKEN=<GitHub access token with `public_repo` scope>

$ export SWIFTWEEKLY_TOKEN=access_token

# usage: ruby ./github_issue_generator.rb --number=<ISSUE #> --date=<DATE (MMMM d, YYYY)>

$ ruby ./github_issue_generator.rb --number=1 --date='December 6, 2015'

# more options and help:

$ ruby ./github_issue_generator.rb --help

Boilerplate for proposal updates

You can generate the boilerplate (eg. SE-NNNN is under review) with the proposal.rb script.

Example:

# usage: ruby ./proposal.rb url-to-proposal url-to-forums status
# in which status is one of 'accepted', 'returned', 'rejected' or 'review'.

$ ruby ./proposal.rb https://github.com/apple/swift-evolution/blob/master/proposals/0231-optional-iteration.md https://forums.swift.org/t/rejected-se-0231-optional-iteration/17805 rejected

# generates the following:

# [SE-0231](https://github.com/apple/swift-evolution/blob/master/proposals/0231-optional-iteration.md) was [rejected](https://forums.swift.org/t/rejected-se-0231-optional-iteration/17805).

Preview the site locally, with drafts

$ bundle exec jekyll build --future --drafts 

# -- or --

$ bundle exec jekyll serve --future --drafts --watch

📝 Writing style guide

We encourage all writes to use their own voice and express their own personality in their writing. This is what makes a great issue.

Some guidelines on writing style:

  • All content must align with Our Standards, outlined in the Code of Conduct. Language must be welcoming, inclusive, respectful, etc.

  • Maintain an overall positive tone. We want to avoid being overly negative. However, this does not mean we should not be critical. Constructive criticism is valid and should be presented in non-aggressive way.

  • Use simple past tense. This is simpler and easier to read, flows better, and is particularly easier for ESL readers. Example:

    • Do this: "Chris Lattner wrote a manifesto." ✅
    • Not this: "A manifesto was written by Chris Lattner." ❌

  • Avoid jargon and abbreviations when possible.

    • Example: use pull request rather than PR
    • Example: write for example rather than e.g.

  • Avoid contractions if possible. Again, this is easier to read, especially for ESL readers.

    • Example: use do not rather than don't.

  • For the "Commits and pull requests" section use the format: PERSON did ACTION.

    • Example: "Chris Lattner opened a pull request for a prototype of async/await."

🕵️‍♀️ Evaluating Swift Forum content

Not all forum discussions are important and valuable enough to be listed in the newsletter. There can be a lot of noise and bikeshedding that simply is not relevant to readers — or ideas are not solid enough. Try to avoid these and focus on "big picture" ideas and discussions pertinent to current or future proposals.

Some good indications on whether or not a discussion is worth including:

  • There is a lot of activity and replies.
  • The Core Team or broader Swift team has responded positively.
  • The Core Team or broader Swift team is highly engaged in the discussion.

💡 Note: This does not mean that discussions without these characteristics are not worth mentioning. These are simply a few guidelines.

📰 Publishing an issue

💡 Note: We publish every other Thursday.

New issues should be pushed to master before noon Pacific Time, preferably around 10 or 11 a.m. if possible. Pushing early allows us to catch and fix any last minute errors. If there are any problems, contact Bas or Jesse.

  1. When ready to publish, move the .md file from _drafts/ to the _posts/ directory.
  2. Run jekyll build on your local copy to preview.
  3. Make sure everything looks good. 👌
  4. Submit a pull request or push to master. 🎉

Emails

Emails are automatically sent via Mailchimp's RSS-to-Email feature. Publishing too late (at or after noon PST) will prevent emails from being sent. If emails fail to send on Thursday at noon PST, Mailchimp will retry on Friday at noon PST.

Tweets

Tweets from @swiftlybrief are automated via IFTTT.

🎢 Continuous integration

We use travis-ci, danger, and proselint (via danger-prose). This ensures:

  • We're always pushing valid markdown and jekyll can build the site.
  • We write elegant prose — no grammar/spelling mistakes, and no offensive or unwelcoming language. See the Dangerfile for more details.

💡Tips

  • Watch all of the main Apple repositories.
  • Follow the prominent contributors on GitHub and Twitter.
  • Monitor and follow discussions on the Swift Forums, and configure your notification settings.
  • Starter tasks: check this filter.
  • When in doubt, refer to previous issues for examples.
  • Keep a draft running throughout the week, add a little bit of content each day.