|
1 |
| -# Contribution Guidelines for API Cookbook Repository |
| 1 | +# Contributing to Perplexity API Cookbook |
2 | 2 |
|
3 |
| -Thank you for your interest in contributing to our API Cookbook repository! We're looking for high-quality, impactful projects that showcase the capabilities of our API and provide genuine value to developers. |
| 3 | +Thank you for your interest in contributing to our API Cookbook! We welcome high-quality examples that showcase the capabilities of Perplexity's Sonar API. |
4 | 4 |
|
5 |
| -## Project Quality Standards |
| 5 | +## Structure |
6 | 6 |
|
7 |
| -We prioritize quality over quantity in all contributions. Here's what we look for: |
| 7 | +This cookbook contains two main sections: |
8 | 8 |
|
9 |
| -### Technical Requirements |
| 9 | +### 1. **Examples** (`/docs/examples/`) |
| 10 | +Step-by-step tutorials and example implementations that teach specific concepts or solve common use cases. |
10 | 11 |
|
11 |
| -- **Functional Completeness**: Your project should be fully functional, free of bugs, and include proper error handling. |
12 |
| -- **Code Quality**: Code should be clean, well-formatted, well-documented, and follow standard best practices for the language/framework used. |
13 |
| -- **Documentation**: Include comprehensive README with: |
14 |
| - - Clear description of what the project does |
15 |
| - - Installation/setup instructions |
16 |
| - - Usage examples |
17 |
| - - Explanation of how the API is leveraged |
18 |
| - - Any limitations or considerations |
19 |
| -- **Maintainability**: Code should be structured to be easily maintained and extended. |
| 12 | +### 2. **Showcase** (`/docs/showcase/`) |
| 13 | +Community-built projects that demonstrate real-world applications of the Sonar API. |
20 | 14 |
|
21 |
| -### Impact Criteria |
| 15 | +## Contributing Guidelines |
22 | 16 |
|
23 |
| -We're especially interested in projects that demonstrate one or more of the following: |
| 17 | +### What We're Looking For |
24 | 18 |
|
25 |
| -1. **Solves Real Problems**: Addresses actual use cases that developers might encounter |
26 |
| -2. **Educational Value**: Teaches important concepts about API usage or implementation patterns |
27 |
| -3. **Novel Applications**: Shows innovative or unexpected ways to leverage the API |
28 |
| -4. **Vertical-Specific Solutions**: Demonstrates the API's utility in specific industries or domains |
29 |
| -5. **Integration Examples**: Shows how to effectively combine our API with other tools or services |
| 19 | +- **Clear, educational content** that helps developers understand how to use the Sonar API effectively |
| 20 | +- **Real-world use cases** that solve actual problems |
| 21 | +- **Well-documented code** with clear explanations |
| 22 | +- **Novel applications** that showcase unique ways to leverage the API |
30 | 23 |
|
31 |
| -## Submission Process |
| 24 | +### Submission Format |
32 | 25 |
|
33 |
| -1. **Fork the Repository**: Create your own fork of the cookbook repository |
34 |
| -2. **Create a New Directory**: Name it descriptively after your project |
35 |
| -3. **Implement Your Project**: Follow the quality guidelines above |
36 |
| -4. **Test Thoroughly**: Ensure everything works as expected |
37 |
| -5. **Update the README**: Add your project to the README for visibility. |
38 |
| -5. **Submit a Pull Request**: Include a detailed description of your project and what makes it valuable |
| 26 | +All contributions should be in MDX format. If your project includes a full application (web app, CLI tool, etc.), host it in a separate public repository and link to it from your MDX file. |
39 | 27 |
|
40 |
| -## Review Criteria |
| 28 | +### MDX File Structure |
41 | 29 |
|
42 |
| -When reviewing submissions, we evaluate based on: |
| 30 | +Your MDX file should include: |
43 | 31 |
|
44 |
| -- **Functionality**: Does it work as described? |
45 |
| -- **Code Quality**: Is the implementation well-crafted? |
46 |
| -- **Originality**: Does it add something new to the cookbook? |
47 |
| -- **Usefulness**: Would other developers find this helpful? |
48 |
| -- **Documentation**: Is it well-explained and easy to follow? |
| 32 | +```mdx |
| 33 | +--- |
| 34 | +title: Your Project Title |
| 35 | +description: A concise description of what your project does |
| 36 | +sidebar_position: 1 |
| 37 | +keywords: [relevant, keywords, for, search] |
| 38 | +--- |
49 | 39 |
|
50 |
| -## Examples of High-Impact Projects |
| 40 | +# Project Title |
51 | 41 |
|
52 |
| -- A specialized search application focused on a particular domain (e.g., legal research, academic papers) |
53 |
| -- A browser extension that enhances productivity or learning |
54 |
| -- An automated workflow tool that solves a specific business problem |
55 |
| -- An integration with popular platforms or productivity tools |
56 |
| -- An innovative data visualization of API results |
57 |
| -- A tool addressing a specific industry challenge |
| 42 | +Brief introduction explaining what your project does and why it's useful. |
58 | 43 |
|
59 |
| -## What to Avoid |
| 44 | +## Features |
| 45 | + |
| 46 | +- Key feature 1 |
| 47 | +- Key feature 2 |
| 48 | +- Key feature 3 |
| 49 | + |
| 50 | +## Prerequisites |
| 51 | + |
| 52 | +What users need before they can use your project. |
| 53 | + |
| 54 | +## Installation |
| 55 | + |
| 56 | +Step-by-step installation instructions. |
60 | 57 |
|
61 |
| -- Projects with minimal functionality beyond basic API calls |
62 |
| -- Poorly documented implementations |
63 |
| -- Projects that essentially duplicate existing cookbook examples |
64 |
| -- Code with security issues or significant bugs |
65 |
| -- Projects focused on prohibited use cases |
| 58 | +## Usage |
66 | 59 |
|
67 |
| -Thank you for helping us build a valuable resource for our developer community! We look forward to seeing your innovative applications of our API. |
| 60 | +Clear examples of how to use your project. |
68 | 61 |
|
69 |
| -## Pull Request Process |
| 62 | +## Code Explanation |
70 | 63 |
|
71 |
| -1. Ensure any install or build dependencies are removed before the end of the layer when doing a |
72 |
| - build. |
73 |
| -2. Update the README.md with details of changes to the interface, this includes new environment |
74 |
| - variables, exposed ports, useful file locations and container parameters. |
75 |
| -3. Increase the version numbers in any examples files and the README.md to the new version that this |
76 |
| - Pull Request would represent. |
77 |
| -4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you |
78 |
| - do not have permission to do that, you may request the second reviewer to merge it for you. |
| 64 | +Key code snippets with explanations of how they work. |
79 | 65 |
|
80 |
| -## Code of Conduct |
| 66 | +## Links |
81 | 67 |
|
82 |
| -### Our Pledge |
| 68 | +- [GitHub Repository](https://github.com/yourusername/yourproject) |
| 69 | +- [Live Demo](https://yourproject.com) (if applicable) |
83 | 70 |
|
84 |
| -In the interest of fostering an open and welcoming environment, we as |
85 |
| -contributors and maintainers pledge to making participation in our project and |
86 |
| -our community a harassment-free experience for everyone, regardless of age, body |
87 |
| -size, disability, ethnicity, gender identity and expression, level of experience, |
88 |
| -nationality, personal appearance, race, religion, or sexual identity and |
89 |
| -orientation. |
| 71 | +## Limitations |
90 | 72 |
|
91 |
| -### Our Standards |
| 73 | +Any known limitations or considerations users should be aware of. |
| 74 | +``` |
92 | 75 |
|
93 |
| -Examples of behavior that contributes to creating a positive environment |
94 |
| -include: |
| 76 | +## How to Submit |
95 | 77 |
|
96 |
| -* Using welcoming and inclusive language |
97 |
| -* Being respectful of differing viewpoints and experiences |
98 |
| -* Gracefully accepting constructive criticism |
99 |
| -* Focusing on what is best for the community |
100 |
| -* Showing empathy towards other community members |
| 78 | +### For Examples |
101 | 79 |
|
102 |
| -Examples of unacceptable behavior by participants include: |
| 80 | +1. Fork this repository |
| 81 | +2. Create a new directory under `/docs/examples/your-example-name/` |
| 82 | +3. Add your `README.mdx` file following the structure above |
| 83 | +4. Include any necessary code snippets in your MDX file |
| 84 | +5. Submit a pull request |
103 | 85 |
|
104 |
| -* The use of sexualized language or imagery and unwelcome sexual attention or |
105 |
| -advances |
106 |
| -* Trolling, insulting/derogatory comments, and personal or political attacks |
107 |
| -* Public or private harassment |
108 |
| -* Publishing others' private information, such as a physical or electronic |
109 |
| - address, without explicit permission |
110 |
| -* Other conduct which could reasonably be considered inappropriate in a |
111 |
| - professional setting |
| 86 | +### For Showcase Projects |
112 | 87 |
|
113 |
| -### Our Responsibilities |
| 88 | +1. Build your project in a separate public repository |
| 89 | +2. Fork this repository |
| 90 | +3. Create a new MDX file under `/docs/showcase/your-project-name.mdx` |
| 91 | +4. Include screenshots or demos if applicable |
| 92 | +5. Submit a pull request |
114 | 93 |
|
115 |
| -Project maintainers are responsible for clarifying the standards of acceptable |
116 |
| -behavior and are expected to take appropriate and fair corrective action in |
117 |
| -response to any instances of unacceptable behavior. |
| 94 | +## Pull Request Template |
118 | 95 |
|
119 |
| -Project maintainers have the right and responsibility to remove, edit, or |
120 |
| -reject comments, commits, code, wiki edits, issues, and other contributions |
121 |
| -that are not aligned to this Code of Conduct, or to ban temporarily or |
122 |
| -permanently any contributor for other behaviors that they deem inappropriate, |
123 |
| -threatening, offensive, or harmful. |
| 96 | +When submitting a PR, please use this template: |
124 | 97 |
|
125 |
| -### Scope |
| 98 | +```markdown |
| 99 | +## Description |
| 100 | +Brief description of your contribution |
126 | 101 |
|
127 |
| -This Code of Conduct applies both within project spaces and in public spaces |
128 |
| -when an individual is representing the project or its community. Examples of |
129 |
| -representing a project or community include using an official project e-mail |
130 |
| -address, posting via an official social media account, or acting as an appointed |
131 |
| -representative at an online or offline event. Representation of a project may be |
132 |
| -further defined and clarified by project maintainers. |
| 102 | +## Type of Contribution |
| 103 | +- [ ] Example Tutorial |
| 104 | +- [ ] Showcase Project |
133 | 105 |
|
134 |
| -### Enforcement |
| 106 | +## Checklist |
| 107 | +- [ ] My code follows the cookbook's style guidelines |
| 108 | +- [ ] I have included comprehensive documentation |
| 109 | +- [ ] I have tested my code and it works as expected |
| 110 | +- [ ] I have included all necessary dependencies and setup instructions |
| 111 | +- [ ] My MDX file includes proper frontmatter (title, description, keywords) |
| 112 | +- [ ] I have linked to any external repositories or live demos |
135 | 113 |
|
136 |
| -Instances of abusive, harassing, or otherwise unacceptable behavior may be |
137 |
| -reported by contacting the project team at [[email protected]]. All |
138 |
| -complaints will be reviewed and investigated and will result in a response that |
139 |
| -is deemed necessary and appropriate to the circumstances. The project team is |
140 |
| -obligated to maintain confidentiality with regard to the reporter of an incident. |
141 |
| -Further details of specific enforcement policies may be posted separately. |
| 114 | +## Project Details |
| 115 | +**What problem does this solve?** |
| 116 | + |
| 117 | +**What makes this contribution valuable to other developers?** |
| 118 | + |
| 119 | +**External Links (if applicable):** |
| 120 | +- GitHub Repository: |
| 121 | +- Live Demo: |
| 122 | +- Blog Post/Article: |
| 123 | +``` |
| 124 | + |
| 125 | +## Code Quality Standards |
| 126 | + |
| 127 | +- Use clear, descriptive variable and function names |
| 128 | +- Include comments for complex logic |
| 129 | +- Follow the language's standard conventions |
| 130 | +- Handle errors appropriately |
| 131 | +- Include example environment variables (without actual keys) |
| 132 | + |
| 133 | +## What to Avoid |
142 | 134 |
|
143 |
| -Project maintainers who do not follow or enforce the Code of Conduct in good |
144 |
| -faith may face temporary or permanent repercussions as determined by other |
145 |
| -members of the project's leadership. |
| 135 | +- Basic "Hello World" examples that don't demonstrate real use cases |
| 136 | +- Duplicates of existing cookbook examples |
| 137 | +- Projects with security vulnerabilities |
| 138 | +- Poorly documented code |
146 | 139 |
|
147 |
| -### Attribution |
| 140 | +## Need Help? |
148 | 141 |
|
149 |
| -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, |
150 |
| -available at [http://contributor-covenant.org/version/1/4][version] |
| 142 | +If you have questions about contributing, please: |
| 143 | +1. Check existing examples for reference |
| 144 | +2. Open an issue for discussion before starting major work |
| 145 | +3. Contact us at [email protected] for specific questions |
151 | 146 |
|
152 |
| -[homepage]: http://contributor-covenant.org |
153 |
| -[version]: http://contributor-covenant.org/version/1/4/ |
| 147 | +We look forward to seeing your creative applications of the Perplexity Sonar API! |
0 commit comments