diff --git a/.github/cookbook_pr_template.md b/.github/cookbook_pr_template.md new file mode 100644 index 0000000000..4e73e1f822 --- /dev/null +++ b/.github/cookbook_pr_template.md @@ -0,0 +1,16 @@ +#### Checklist +Ensure the following are addressed before submitting your PR: + +1. **Real-World Usefulness**: + - [ ] Does the task address a practical need in real-world application development? + +2. **Code Quality**: + - [ ] Is the code production-ready, safe, and free of potential security issues? + - [ ] Does the code avoid uncaught exceptions or other potential pitfalls? + +3. **Standard Library and Packages**: + - [ ] For tasks using the Standard Library: Does this recipe provide value beyond what an LLM could easily generate? + - [ ] For tasks using a package: Does this recipe implicitly recommend the package for production use? + +4. **Recipe Redundancy**: + - [ ] Does this recipe duplicate an existing task? If so, does it add value by showing differences between packages or approaches? \ No newline at end of file diff --git a/.github/other_pr_template.md b/.github/other_pr_template.md new file mode 100644 index 0000000000..3c33591eaa --- /dev/null +++ b/.github/other_pr_template.md @@ -0,0 +1,4 @@ +## Checklist + +* [ ] Please format your code using `make fmt` +* [ ] If addressing an open issue, please link to it by writing "Resolves #1234" (use the relevant issue number) \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000000..3b9a8ec330 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,4 @@ +Please go to the `Preview` tab and select the appropriate sub-template: + +* [Other PR](?expand=1&template=other_pr_template.md) +* [OCaml Cookbook Contribution](?expand=1&template=cookbook_pr_template.md) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7f690004fa..630fb0e194 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -147,14 +147,27 @@ compilation error. Each recipe is a way to perform a task using a combination of open-source libraries. -#### OCaml Cookbook Recipe Review Checklist +#### Guidelines for New OCaml Cookbook Recipes -Checklist for reviewing OCaml cookbook submissions: +When contributing new recipes to the OCaml Cookbook, please adhere to the following: -1. does this recipe implement the task it's assigned to? -2. if this recipe is creating a new task: (1) is the new task substantially different from existing tasks, (2) there is no existing task that this recipe solves, (3) is the new task description very clear on what the task is (be specific!) -3. is the code explained sufficiently without overexplaining (be short and focus on what matters)? -4. is the code such that you would put it into production? I.e. are the libraries used stable enough and is the code readable? +1. **Task Selection**: + - Focus on practical, reusable tasks relevant to a wide audience. + - Ensure the task demonstrates idiomatic OCaml usage. + - Avoid tasks that are overly trivial or highly specific to niche cases. + +2. **Code Standards**: + - Write clear, idiomatic OCaml code. + - Ensure the code compiles without errors or warnings. + - Use standard OCaml libraries and tools wherever possible. + +3. **Evaluation Criteria**: + - Does the recipe address a useful real-world task? + - Is the code ready for production use? + - If using a package, does it implicitly recommend the package for production? + - Avoid duplicating existing recipes unless demonstrating package differences. + +Following these guidelines will help us maintain a high-quality and consistent OCaml Cookbook. ### Add A Recurring Event @@ -179,6 +192,7 @@ The Changelog covers developments across: - [OCaml Infrastructure](https://infra.ocaml.org/) - [OCaml.org itself](https://ocaml.org/) + #### Purpose and Audience The primary audience for the Changelog is OCaml users. Content should focus on changes, updates, and news that directly impact users of OCaml and its ecosystem. @@ -207,6 +221,7 @@ To contribute a new post to the Changelog: 4. Write the post content, focusing on how the news or change affects OCaml users. 5. Submit a pull request with your new file. + ## Git and GitHub Workflow The preferred workflow for contributing to a repository is to fork the main repository on GitHub, clone, and develop on a new branch.