Better Contributing and Readme files (match format on Spice repos)
talsraviv
parent
b23d277442
commit
c97f5c5a68
|
|
@ -1,42 +1,59 @@
|
|||
# Contributing an Instant Answer to DuckDuckGo.com
|
||||
|
||||
> You can find the full [DuckDuckHack documentation here](http://docs.duckduckhack.com)
|
||||
## Learn to Make New Instant Answers
|
||||
|
||||
Have an idea [that no one has done yet](https://duck.co/ia)? Improving an [existing Instant Answer](https://duck.co/ia/dev/issues)?
|
||||
Learn to make an Instant Answer by starting with our walkthroughs:
|
||||
|
||||
1. **Before coding, [create an Instant Answer Page](https://duck.co/ia/new_ia) for your idea.** If you're fixing an existing Instant Answer, [locate its existing page](https://duck.co/ia).
|
||||
- Learn how to build a [convenient calculation tool](http://docs.duckduckhack.com/walkthroughs/calculation.html)
|
||||
- Learn how to turn an [external API into delightful search results](http://docs.duckduckhack.com/walkthroughs/forum-lookup.html)
|
||||
- Create a [cheat sheet for a favorite topic](http://docs.duckduckhack.com/walkthroughs/programming-syntax.html)
|
||||
|
||||
> Instant Answer Pages are the "home base" for each Instant Answer. They are where the community plans, collaborates, and tracks the [life cycle](http://docs.duckduckhack.com/submitting/long-term.html) of all Instant Answers. It's where we aggregate pull requests, issues, attribution, and feedback.
|
||||
*UPDATE: We're aiming to have multiple Instant Answers for every programming language and framework. Jump in and help us [fill in the blanks](https://github.com/duckduckgo/duckduckgo/wiki/Programming-IA-Coverage).*
|
||||
|
||||
2. **Hack away, keeping the [Instant Answer Production Guidelines](http://docs.duckduckhack.com/submitting/checklist.html) in mind.**
|
||||
You can find the full [DuckDuckHack documentation here](http://docs.duckduckhack.com).
|
||||
|
||||
## Improve a Live Instant Answer
|
||||
|
||||
We welcome new contributors to dive in and improve live Instant Answers. It's a great, hands-on way to learn how things work:
|
||||
|
||||
- Have a [favorite Instant Answer](http://duck.co/ia) that you want to make even better? Feel free to dive in and make changes.
|
||||
- Help other DuckDuckHackers with their [Instant Answers in development](https://duck.co/ia/dev/pipeline)
|
||||
- Suggest improvements & file bugs for [live Instant Answers](https://duck.co/ia) through the, "Create Issue" button on each IA page
|
||||
- Tackle some of the "low-hanging fruit" and, "high priority" issues on our [Live Issues Page](https://duck.co/ia/dev/issues?tag=lowhangingfruit)
|
||||
|
||||
## Go Live on DuckDuckGo.com
|
||||
|
||||
The final step is to have your contribution appear on DuckDuckGo.com above ads and organic links, on [millions of searches](https://duckduckgo.com/traffic.html).
|
||||
|
||||
1. **[Create an Instant Answer Page](https://duck.co/ia/new_ia) as the home base for your idea.** If you're fixing an existing Instant Answer, [locate its existing page](https://duck.co/ia).
|
||||
|
||||
This page will be the center for feedback, Github issues, attribution, deployment, and collaboration.
|
||||
|
||||
2. **Make sure your contribution meets the [Production Guidelines](http://docs.duckduckhack.com/submitting/checklist.html).**
|
||||
|
||||
3. **[Submit a pull request](http://docs.duckduckhack.com/submitting/pull-request.html).**
|
||||
|
||||
> Make sure to paste your Instant Answer page URL in the description. This will automatically link the two.
|
||||
We're excited to meet you and support you along the way - and it's never too early to say hello. Join us on [Slack](https://quackslack.herokuapp.com) or [email](mailto:open@duckduckgo.com).
|
||||
|
||||
We're excited to meet you and support you along the way - and it's never too early to say hello. Join us on [Slack](mailto:QuackSlack@duckduckgo.com?subject=AddMe) or [email](mailto:open@duckduckgo.com).
|
||||
|
||||
*The opportunities to contribute don't stop here. Learn about [keeping your IA awesome](http://docs.duckduckhack.com/submitting/long-term.html).*
|
||||
|
||||
|
||||
## Pull Request Format
|
||||
## Formatting Your Pull Request
|
||||
|
||||
When submitting a pull request, the following guidelines help speed up the review process:
|
||||
|
||||
If your IA is new, use the format: `"New {IA TOPIC} {IA TYPE}"`. For example:
|
||||
### New Instant Answers
|
||||
|
||||
- "New Instagram Spice"
|
||||
- "New Firefox Cheat Sheet"
|
||||
|
||||
If you're submitting a fix, use the title format: `"{IA NAME}: Brief explanation`. For example:
|
||||
|
||||
- "PeopleInSpace: Use smaller local image, fallback to API when needed."
|
||||
|
||||
Include the issue number in the description (conveniently, this will automatically resolve the issue upon merging). Describe your motivation, thought process, and solution in the description. For example:
|
||||
1. New IAs should be titled as follows: **`New {IA TOPIC} {IA TYPE}`**. For example, `New Instagram Spice` or `New Firefox Cheat Sheet`
|
||||
|
||||
- "**Fixes #2038.** The images used by the API are very large and don't change often. I've but a smaller version of each image (and a 2x version for retina screens) in the share directory. The callback will try and load a local image based on the astronauts name and fallback to using the API's image if one does not exist."
|
||||
2. Paste the relevant [Instant Answer Page URL](https://duck.co/ia/new_ia) in the description field. This will automatically link the PR to the Instant Answer.
|
||||
|
||||
### Improvements
|
||||
|
||||
**Finally, don't forget to paste the relevant [Instant Answer Page URL](https://duck.co/ia/new_ia) in the description field**, while creating new pull requests. This will automatically link the two.
|
||||
1. Fixes should be titled as follows: **`{IA NAME}: Brief explanation`**. For example: `PeopleInSpace: Use smaller local image, fallback to API when needed.`
|
||||
|
||||
2. Paste the relevant [Instant Answer Page URL](https://duck.co/ia/new_ia) in the description field. This will automatically link the PR to the Instant Answer.
|
||||
|
||||
3. Include the issue number in the description (conveniently, this will automatically resolve the issue upon merging). Describe your motivation, thought process, and solution in the description. For example:
|
||||
|
||||
"**Fixes #2038.** The images used by the API are very large and don't change often. I've put a smaller version of each image (and a 2x version for retina screens) in the share directory. The callback will try and load a local image based on the astronauts name and fallback to using the API's image if one does not exist."
|
||||
|
||||
> **IMPORTANT:** Don't worry if you get an initial error regarding failing Travis tests. The reason is that your IA page hasn't yet been moved out of the "Planning" status - which only community leaders/staff can do. As long as the ID in your IA page matches the ID in your code, and you've pasted the URL to your IA page, you can ignore this initial error.
|
||||
|
||||
|
|
|
|||
44
README.md
44
README.md
|
|
@ -4,31 +4,37 @@
|
|||
|
||||
|
||||
|
||||
**Instant Answers are an opportunity for anyone to create their own search results.**
|
||||
**We're a community dedicated to making delightful search results for everyone. We do this using existing APIs, external data sets, or just some well-placed code.**
|
||||
|
||||
Instant Answers appear on DuckDuckGo.com above ads and organic links, on [millions of searches](https://duckduckgo.com/traffic.html). Instant Answers are created by an open source community of developers [around the world](http://duckduckgo.meetup.com/) like you. Welcome!
|
||||
*Instant Answers* appear on DuckDuckGo.com above ads and organic links, on [millions of searches](https://duckduckgo.com/traffic.html). Instant Answers are created by an open source community of developers [around the world](http://duckduckgo.meetup.com/) like yourself. Welcome!
|
||||
|
||||
You can find the [full documentation here](http://docs.duckduckhack.com). This is the repository for [one type of Instant Answers](http://docs.duckduckhack.com/welcome/determining-ia-type.html), called Goodies.
|
||||
*You can find the [full documentation here](http://docs.duckduckhack.com).*
|
||||
|
||||
## Create a New Instant Answer
|
||||
## Jump Right In
|
||||
|
||||
Learn to make an Instant Answer by starting with any of our quick tutorials. All of these are self-contained and will get you up and running. Pick whatever looks most interesting!
|
||||
The best way to learn about Instant Answers is to dive in with a walkthrough:
|
||||
|
||||
- **[Create a programming syntax cheat sheet](http://docs.duckduckhack.com/walkthroughs/programming-syntax.html)**
|
||||
- **[Create a quick online calculation](http://docs.duckduckhack.com/walkthroughs/calculation.html)**
|
||||
- **[Build an API-based lookup](http://docs.duckduckhack.com/walkthroughs/forum-lookup.html)**
|
||||
- Learn how to build a [convenient calculation tool](http://docs.duckduckhack.com/walkthroughs/calculation.html)
|
||||
- Learn how to turn an [external API into delightful search results](http://docs.duckduckhack.com/walkthroughs/forum-lookup.html)
|
||||
- Create a [cheat sheet for a favorite topic](http://docs.duckduckhack.com/walkthroughs/programming-syntax.html)
|
||||
|
||||
## Improve a Live Instant Answer
|
||||
We also welcome new contributors to learn by improving existing Instant Answers:
|
||||
|
||||
We welcome new contributors to dive in and improve live Instant Answers. It's a great, hands-on way to learn how things work. Start by [setting up your development environment](http://docs.duckduckhack.com/welcome/setup-dev-environment.html).
|
||||
- Tackle some of the "low-hanging fruit" and, "high priority" issues on our [Live Issues Page](https://duck.co/ia/dev/issues?tag=lowhangingfruit)
|
||||
- Help other DuckDuckHackers with their [Instant Answers in development](https://duck.co/ia/dev/pipeline)
|
||||
- Suggest improvements & file bugs for [live Instant Answers](https://duck.co/ia) through the, "Create Issue" button on each IA page
|
||||
- Have a [favorite Instant Answer](http://duck.co/ia) that you want to make even better? Feel free to dive in and make changes.
|
||||
|
||||
You can see all "low-hanging fruit" issues neatly organized in one place on our [Live Issues Page](https://duck.co/ia/dev/issues?tag=lowhangingfruit), or get an overview of all [Instant Answers in development](https://duck.co/ia/dev/pipeline).
|
||||
|
||||
Have a [favorite Instant Answer](http://duck.co/ia) that you want to make even better? Feel free to dive in and make changes.
|
||||
## Say Hello
|
||||
|
||||
## Inspiration
|
||||
[ You should definitely join us on Slack](https://quackslack.herokuapp.com) (you can also [email us](mailto:open@duckduckgo.com)).
|
||||
|
||||
Instant Answers allow you to create your own search results. Here are some examples of what contributors have created. You can see [all live Instant Answers listed here](https://duck.co/ia).
|
||||
P.S.We're a digital community, but real people - we frequently meet up to hack together. Check out our [global meetups](http://duckduckgo.meetup.com/).
|
||||
|
||||
## Live Instant Answers Made by the Community
|
||||
|
||||
Here are some examples of what contributors have created. You can see [all live Instant Answers listed here](https://duck.co/ia).
|
||||
|
||||
Instant Answers can be quite dynamic...
|
||||
|
||||
|
|
@ -63,13 +69,3 @@ Other Instant Answers channel external sources (API requests):
|
|||
|
||||
|
||||
The [possibilities are endless](https://duck.co/ia). **Our community's mission is to cover every topic with a community-generated Instant Answer.**
|
||||
|
||||
## Discuss with Us
|
||||
|
||||
Want help? Need to think out loud?
|
||||
|
||||
[ Talk to us on Slack](mailto:QuackSlack@duckduckgo.com?subject=AddMe) or [email us](mailto:open@duckduckgo.com).
|
||||
|
||||
We're a digital community, but real people - we frequently meet up to hack together. Check out our [global meetups](http://duckduckgo.meetup.com/).
|
||||
|
||||
You can find the [full documentation here](http://docs.duckduckhack.com).
|
||||
|
|
|
|||
Loading…
Reference in New Issue