Skip to content

Commit 60a3688

Browse files
committed
chore(docs): update contributing guidelines and add pull request template
1 parent 2007445 commit 60a3688

File tree

3 files changed

+155
-114
lines changed

3 files changed

+155
-114
lines changed

.github/pull_request_template.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
## Description
2+
Brief description of your contribution
3+
4+
## Type of Contribution
5+
- [ ] Example Tutorial
6+
- [ ] Showcase Project
7+
- [ ] Documentation Update
8+
- [ ] Bug Fix
9+
- [ ] Other (please describe)
10+
11+
## Checklist
12+
- [ ] My code follows the cookbook's style guidelines
13+
- [ ] I have included comprehensive documentation
14+
- [ ] I have tested my code and it works as expected
15+
- [ ] I have included all necessary dependencies and setup instructions
16+
- [ ] My MDX file includes proper frontmatter (title, description, keywords)
17+
- [ ] I have linked to any external repositories or live demos
18+
19+
## Project Details
20+
**What problem does this solve?**
21+
<!-- Describe the problem or use case your contribution addresses -->
22+
23+
**What makes this contribution valuable to other developers?**
24+
<!-- Explain why this would be helpful to others using the Perplexity Sonar API -->
25+
26+
**External Links (if applicable):**
27+
- GitHub Repository:
28+
- Live Demo:
29+
- Blog Post/Article:
30+
31+
## Testing
32+
<!-- Describe how you tested your contribution -->
33+
34+
## Screenshots (if applicable)
35+
<!-- Add screenshots to help explain your contribution -->
36+
37+
## Additional Notes
38+
<!-- Any additional information that might be helpful for reviewers -->

CONTRIBUTING.md

Lines changed: 108 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -1,153 +1,147 @@
1-
# Contribution Guidelines for API Cookbook Repository
1+
# Contributing to Perplexity API Cookbook
22

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.
44

5-
## Project Quality Standards
5+
## Structure
66

7-
We prioritize quality over quantity in all contributions. Here's what we look for:
7+
This cookbook contains two main sections:
88

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.
1011

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.
2014

21-
### Impact Criteria
15+
## Contributing Guidelines
2216

23-
We're especially interested in projects that demonstrate one or more of the following:
17+
### What We're Looking For
2418

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
3023

31-
## Submission Process
24+
### Submission Format
3225

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.
3927

40-
## Review Criteria
28+
### MDX File Structure
4129

42-
When reviewing submissions, we evaluate based on:
30+
Your MDX file should include:
4331

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+
---
4939

50-
## Examples of High-Impact Projects
40+
# Project Title
5141

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.
5843

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.
6057

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
6659

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.
6861

69-
## Pull Request Process
62+
## Code Explanation
7063

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.
7965

80-
## Code of Conduct
66+
## Links
8167

82-
### Our Pledge
68+
- [GitHub Repository](https://github.com/yourusername/yourproject)
69+
- [Live Demo](https://yourproject.com) (if applicable)
8370

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
9072

91-
### Our Standards
73+
Any known limitations or considerations users should be aware of.
74+
```
9275

93-
Examples of behavior that contributes to creating a positive environment
94-
include:
76+
## How to Submit
9577

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
10179

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
10385

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
11287

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
11493

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
11895

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:
12497

125-
### Scope
98+
```markdown
99+
## Description
100+
Brief description of your contribution
126101

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
133105

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
135113

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
142134

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
146139

147-
### Attribution
140+
## Need Help?
148141

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
151146

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!

README.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,12 @@ Example code and guides for accomplishing common tasks with the [Perplexity Sona
1212

1313

1414
For more information, check our [docs](https://docs.perplexity.ai).
15+
16+
## Contributing
17+
18+
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to submit examples and showcase projects.
19+
20+
### Quick Links
21+
- [Submit an Example Tutorial](CONTRIBUTING.md#for-examples)
22+
- [Submit a Showcase Project](CONTRIBUTING.md#for-showcase-projects)
23+
- [View Contribution Guidelines](CONTRIBUTING.md)

0 commit comments

Comments
 (0)