Add code-review best practices

bin/best-practice-content.cjs

@@ -0,0 +1,173 @@
+const fs = require('fs');
+const path = require('path');
+
+const OPEN_AI_API_KEY = process.env.OPEN_AI_API_KEY;
+const ALL_BEST_PRACTICES_DIR = path.join(
+  __dirname,
+  '../src/data/best-practices'
+);
+const BEST_PRACTICE_JSON_DIR = path.join(
+  __dirname,
+  '../public/jsons/best-practices'
+);
+
+const bestPracticeId = process.argv[2];
+const bestPracticeTitle = bestPracticeId.replace(/-/g, ' ');
+
+const allowedBestPracticeIds = fs.readdirSync(ALL_BEST_PRACTICES_DIR);
+if (!bestPracticeId) {
+  console.error('bestPracticeId is required');
+  process.exit(1);
+}
+
+if (!allowedBestPracticeIds.includes(bestPracticeId)) {
+  console.error(`Invalid bestPractice key ${bestPracticeId}`);
+  console.error(`Allowed keys are ${allowedBestPracticeIds.join(', ')}`);
+  process.exit(1);
+}
+
+const BEST_PRACTICE_CONTENT_DIR = path.join(
+  ALL_BEST_PRACTICES_DIR,
+  bestPracticeId,
+  'content'
+);
+const { Configuration, OpenAIApi } = require('openai');
+const configuration = new Configuration({
+  apiKey: OPEN_AI_API_KEY,
+});
+
+const openai = new OpenAIApi(configuration);
+
+function getFilesInFolder(folderPath, fileList = {}) {
+  const files = fs.readdirSync(folderPath);
+
+  files.forEach((file) => {
+    const filePath = path.join(folderPath, file);
+    const stats = fs.statSync(filePath);
+
+    if (stats.isDirectory()) {
+      getFilesInFolder(filePath, fileList);
+    } else if (stats.isFile()) {
+      const fileUrl = filePath
+        .replace(BEST_PRACTICE_CONTENT_DIR, '') // Remove the content folder
+        .replace(/\/\d+-/g, '/') // Remove ordering info `/101-ecosystem`
+        .replace(/\/index\.md$/, '') // Make the `/index.md` to become the parent folder only
+        .replace(/\.md$/, ''); // Remove `.md` from the end of file
+
+      fileList[fileUrl] = filePath;
+    }
+  });
+
+  return fileList;
+}
+
+function writeTopicContent(topicTitle) {
+  let prompt = `I am reading best-practices about "${bestPracticeTitle}". I want to know more about "${parentTopic}". Why is it important? Content should be in markdown. Behave as if you are the author of the best practices.`;
+
+  console.log(`Generating '${topicTitle || parentTopic}'...`);
+
+  return new Promise((resolve, reject) => {
+    openai
+      .createChatCompletion({
+        model: 'gpt-4',
+        messages: [
+          {
+            role: 'user',
+            content: prompt,
+          },
+        ],
+      })
+      .then((response) => {
+        const article = response.data.choices[0].message.content;
+
+        resolve(article);
+      })
+      .catch((err) => {
+        reject(err);
+      });
+  });
+}
+
+async function writeFileForGroup(group, topicUrlToPathMapping) {
+  const topicId = group?.properties?.controlName;
+  const topicTitle = group?.children?.controls?.control?.find(
+    (control) => control?.typeID === 'Label'
+  )?.properties?.text;
+  const currTopicUrl = `/${topicId}`;
+  if (currTopicUrl.startsWith('/check:')) {
+    return;
+  }
+
+  const contentFilePath = topicUrlToPathMapping[currTopicUrl];
+
+  if (!contentFilePath) {
+    console.log(`Missing file for: ${currTopicUrl}`);
+    process.exit(0);
+    return;
+  }
+
+  const currentFileContent = fs.readFileSync(contentFilePath, 'utf8');
+  const isFileEmpty = currentFileContent.replace(/^#.+/, ``).trim() === '';
+
+  if (!isFileEmpty) {
+    console.log(`Ignoring ${topicId}. Not empty.`);
+    return;
+  }
+
+  let newFileContent = `# ${topicTitle}`;
+
+  if (!OPEN_AI_API_KEY) {
+    console.log(`Writing ${topicId}..`);
+
+    fs.writeFileSync(contentFilePath, newFileContent, 'utf8');
+    return;
+  }
+
+  const topicContent = await writeTopicContent(topicTitle);
+  newFileContent += `\n\n${topicContent}`;
+
+  console.log(`Writing ${topicId}..`);
+  fs.writeFileSync(contentFilePath, newFileContent, 'utf8');
+
+  // console.log(currentFileContent);
+  // console.log(currTopicUrl);
+  // console.log(topicTitle);
+  // console.log(topicUrlToPathMapping[currTopicUrl]);
+}
+
+async function run() {
+  const topicUrlToPathMapping = getFilesInFolder(BEST_PRACTICE_CONTENT_DIR);
+
+  const bestPracticeJson = require(path.join(
+    BEST_PRACTICE_JSON_DIR,
+    `${bestPracticeId}.json`
+  ));
+  const groups = bestPracticeJson?.mockup?.controls?.control?.filter(
+    (control) =>
+      control.typeID === '__group__' &&
+      !control.properties?.controlName?.startsWith('ext_link')
+  );
+
+  if (!OPEN_AI_API_KEY) {
+    console.log('----------------------------------------');
+    console.log('OPEN_AI_API_KEY not found. Skipping openai api calls...');
+    console.log('----------------------------------------');
+  }
+
+  const writePromises = [];
+  for (let group of groups) {
+    writePromises.push(writeFileForGroup(group, topicUrlToPathMapping));
+  }
+
+  console.log('Waiting for all files to be written...');
+  await Promise.all(writePromises);
+}
+
+run()
+  .then(() => {
+    console.log('Done');
+  })
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

bin/roadmap-content.cjs

@@ -59,8 +59,7 @@ function writeTopicContent(currTopicUrl) {
     .slice(-2)
     .map((topic) => topic.replace(/-/g, ' '));
 
-  // const roadmapTitle = roadmapId.replace(/-/g, ' ');
+  const roadmapTitle = roadmapId.replace(/-/g, ' ');
-  const roadmapTitle = 'PostgreSQL';
 
   let prompt = `I am reading a guide about "${roadmapTitle}". I am on the topic "${parentTopic}". I want to know more about "${childTopic}". Write me a brief summary for that topic. Content should be in markdown. Behave as if you are the author of the guide.`;
   if (!childTopic) {

package.json

@@ -17,6 +17,7 @@
     "roadmap-dirs": "node bin/roadmap-dirs.cjs",
     "roadmap-content": "node bin/roadmap-content.cjs",
     "best-practice-dirs": "node bin/best-practice-dirs.cjs",
+    "best-practice-content": "node bin/best-practice-content.cjs",
     "test:e2e": "playwright test"
   },
   "dependencies": {

src/data/best-practices/code-review/code-review.md

@@ -10,7 +10,7 @@ title: 'Code Review Best Practices'
 description: 'Detailed list of best practices for effective code reviews and quality'
 dimensions:
   width: 968
-  height: 3429.4
+  height: 3254.98
 schema:
   headline: 'Code Review Best Practices'
   description: 'Discover the essential best practices for effective code review and improve the quality of your software development. From establishing clear objectives to providing constructive feedback, this interactive guide covers everything you need to know to optimize your code review process and ensure the delivery of high-quality code.'

src/data/best-practices/code-review/content/address-author-concerns.md

@@ -0,0 +1 @@
+# Address any questions or concerns that the author may have.

src/data/best-practices/code-review/content/address-feedback-received.md

@@ -0,0 +1 @@
+# Address all the feedback received, including any concerns or questions raised.

src/data/best-practices/code-review/content/adequate-review-time.md

@@ -0,0 +1 @@
+# Provide adequate time for code reviews and ensure that it is a priority.

src/data/best-practices/code-review/content/adhere-guidelines.md

@@ -0,0 +1 @@
+# Double-check that the code adheres to the project's coding standards and best practices. 

src/data/best-practices/code-review/content/architecture-understanding.md

@@ -0,0 +1 @@
+# Ensure that you understand the codebase and its architecture.

src/data/best-practices/code-review/content/author-feedback-welcomed.md

@@ -0,0 +1 @@
+# Be open to feedback from the author and be willing to make adjustments to your feedback if necessary.

src/data/best-practices/code-review/content/celebrate-success.md

@@ -0,0 +1 @@
+# Celebrate the successful completion of the code change!

src/data/best-practices/code-review/content/change-functioning.md

@@ -0,0 +1 @@
+# Verify that the code change is functioning as expected in the production environment.

src/data/best-practices/code-review/content/changes-ready.md

@@ -0,0 +1 @@
+# Ensure that the changes are complete and ready for review, including all necessary tests and documentation.

src/data/best-practices/code-review/content/clear-feedback.md

@@ -0,0 +1 @@
+# Provide clear and actionable feedback, including specific suggestions for improvement and explanations of any concerns.

src/data/best-practices/code-review/content/code-guide-best-practices-adherence.md

@@ -0,0 +1 @@
+# Ensure that the code change adheres to the project's coding standards and best practices.

src/data/best-practices/code-review/content/code-review-purpose.md

@@ -0,0 +1 @@
+# Ensure that the purpose of code reviews is clear to everyone.

src/data/best-practices/code-review/content/collaborate-reviewer-author.md

@@ -0,0 +1 @@
+# Be willing to collaborate with the author to resolve any issues or concerns that arise during the review process.

src/data/best-practices/code-review/content/complex-tasks-breakage.md

@@ -0,0 +1 @@
+# Break down complex tasks into smaller easily manageable PRs.

src/data/best-practices/code-review/content/conflict-resolution.md

@@ -0,0 +1 @@
+# Define a process for conflict resolution in code reviews.

src/data/best-practices/code-review/content/consistency-everywhere.md

@@ -0,0 +1 @@
+# Stay consistent with the overall project design and architecture.

src/data/best-practices/code-review/content/continuous-improvement-over-perfection.md

@@ -0,0 +1 @@
+# Seek continuous improvement, not perfection.

src/data/best-practices/code-review/content/cross-functional-knowledge.md

@@ -0,0 +1 @@
+# Encourage reviewing code in unknown-areas for cross-functional knowledge.

src/data/best-practices/code-review/content/definition-of-done.md

@@ -0,0 +1 @@
+# Ensure that “Definition of Done” is documented and clear to everyone

src/data/best-practices/code-review/content/determine-review-level.md

@@ -0,0 +1 @@
+# Determine the appropriate level of review needed based on the scope and impact of the code change.

src/data/best-practices/code-review/content/document-new-feature.md

@@ -0,0 +1 @@
+# Write the documentation for the feature or changes if required.

src/data/best-practices/code-review/content/document-process.md

@@ -0,0 +1 @@
+# Document and standardize the code review process.

src/data/best-practices/code-review/content/encourage-participation.md

@@ -0,0 +1 @@
+# Encourage team members to participate in code reviews.

src/data/best-practices/code-review/content/failing-text-bug.md

@@ -0,0 +1 @@
+# Write a failing test if the change is for a bug fix.

src/data/best-practices/code-review/content/follow-guidelines.md

@@ -0,0 +1 @@
+# Follow the coding standards and any other team guidelines.

src/data/best-practices/code-review/content/impact-of-change.md

@@ -0,0 +1 @@
+# Consider the impact of the change on other parts of the system.

src/data/best-practices/code-review/content/implement-changes-explanations.md

@@ -0,0 +1 @@
+# Implement the suggested changes and provide explanations where needed.

src/data/best-practices/code-review/content/index.md

@@ -0,0 +1 @@
+# 

src/data/best-practices/code-review/content/knowledge-sharing.md

@@ -0,0 +1 @@
+# Use code reviews as an opportunity for knowledge sharing and learning.

src/data/best-practices/code-review/content/learn-context-reqs.md

@@ -0,0 +1 @@
+# Understand the requirements and the context in which change was made.

src/data/best-practices/code-review/content/list-review-risks-issues.md

@@ -0,0 +1 @@
+# Make list of any potential risks or issues that could arise with the change.

src/data/best-practices/code-review/content/merge-approved-code.md

@@ -0,0 +1 @@
+# Merge the approved code change into the main/feature branch.

src/data/best-practices/code-review/content/monitor-performance.md

@@ -0,0 +1 @@
+# Monitor the performance and functionality of the code change and address any issues that arise.

src/data/best-practices/code-review/content/monitor-reviews.md

@@ -0,0 +1 @@
+# Constantly monitor and improve code review process.

src/data/best-practices/code-review/content/nitpick-comments.md

@@ -0,0 +1 @@
+# Leave comments to suggest improvements, but prefix it with "Nit" if it's not critical to meeting the standards

src/data/best-practices/code-review/content/no-one-way-process.md

@@ -0,0 +1 @@
+# Encourage communication/collaboration; avoid treating code reviews as a one-way process.

src/data/best-practices/code-review/content/note-questions-for-review.md

@@ -0,0 +1 @@
+# Take notes on any questions or concerns about the change to discuss them during the review.

src/data/best-practices/code-review/content/open-mind-author.md

@@ -0,0 +1 @@
+# Approach the review process with an open mind, and be willing to learn from and collaborate with other team members.

src/data/best-practices/code-review/content/open-mind-reviewer.md

@@ -0,0 +1 @@
+# Approach the process with an open mind; be willing to provide constructive feedback and collaborate to improve code quality

src/data/best-practices/code-review/content/pair-programming-reviews.md

@@ -0,0 +1 @@
+# Consider using pair programming as an alternative or supplement to code reviews.

src/data/best-practices/code-review/content/positive-feedback-criticism.md

@@ -0,0 +1 @@
+# Provide positive feedback in addition to constructive criticism, to reinforce good practices and boost team morale.

src/data/best-practices/code-review/content/potential-issues-review.md

@@ -0,0 +1 @@
+# Identify any potential performance, security, or scalability concerns and note them for discussion during the review.

src/data/best-practices/code-review/content/potential-issues-reviewer.md

@@ -0,0 +1 @@
+# Identify any potential performance, security, or scalability concerns, and discuss them with the author.

src/data/best-practices/code-review/content/prepare-list.md

@@ -0,0 +1 @@
+# Based on the requirements, prepare a list of items that should have been covered in the changes.

src/data/best-practices/code-review/content/prioritize-feedback.md

@@ -0,0 +1 @@
+# Prioritize your feedback, focusing on the most important issues first.

src/data/best-practices/code-review/content/professional-feedback.md

@@ -0,0 +1 @@
+# Be respectful and professional in your feedback, avoiding personal attacks or derogatory comments.

src/data/best-practices/code-review/content/proper-description-pr.md

@@ -0,0 +1 @@
+# Make sure to add proper title, description, any screenshots, relevant links, configuration changes etc in the PR.

src/data/best-practices/code-review/content/quality-code-overall.md

@@ -0,0 +1 @@
+# Consider the overall quality of the code, including readability, maintainability, and scalability.

src/data/best-practices/code-review/content/re-run-tests-verify.md

@@ -0,0 +1 @@
+# Run the tests again and ensure that they all pass.

src/data/best-practices/code-review/content/recognition-rewards.md

@@ -0,0 +1 @@
+# Recognition and rewards for those with track record of quality feedback.

src/data/best-practices/code-review/content/resolve-conflicts-timely.md

@@ -0,0 +1 @@
+# Resolve conflicting opinions in a timely manner; don't let a PR sit around due to disagreement.

src/data/best-practices/code-review/content/review-docs-design.md

@@ -0,0 +1 @@
+# Review any documentation or design specifications related to the change.

src/data/best-practices/code-review/content/review-docs-updated.md

@@ -0,0 +1 @@
+# Ensure that the relevant documentation has been updated.

src/data/best-practices/code-review/content/review-tests.md

@@ -0,0 +1 @@
+# Review any tests included with the code change to verify that they adequately cover the functionality and edge cases.

src/data/best-practices/code-review/content/review-updated-code.md

@@ -0,0 +1 @@
+# Review the updated code and ensure that the suggested changes have been implemented as expected.

src/data/best-practices/code-review/content/run-tests-ensure-passing.md

@@ -0,0 +1 @@
+# Run the tests and ensure that they all pass after making changes

src/data/best-practices/code-review/content/seek-feedback.md

@@ -0,0 +1 @@
+# Encourage authors to seek feedback during development before submitting a formal code review.

src/data/best-practices/code-review/content/seek-team-members-feedback.md

@@ -0,0 +1 @@
+# Seek feedback from other team members if you are unsure about the changes.

src/data/best-practices/code-review/content/self-review.md

@@ -0,0 +1 @@
+# Review your code before submitting for review.

src/data/best-practices/code-review/content/set-clear-expectations.md

@@ -0,0 +1 @@
+# Set clear expectations for code review turnaround times.

src/data/best-practices/code-review/content/short-term-long-term-considerations.md

@@ -0,0 +1 @@
+# Keep the short-term and long-term considerations in mind.

src/data/best-practices/code-review/content/style-guide-preferences.md

@@ -0,0 +1 @@
+# Have a definitive style guide for style preferences.

src/data/best-practices/code-review/content/submit-re-review.md

@@ -0,0 +1 @@
+# Submit the updated code for a second review if needed.

src/data/best-practices/code-review/content/team-wide-style-followed.md

@@ -0,0 +1 @@
+# Team wide styleguide is the absolute authority styling. Verify changes against those instead of personal preferences

src/data/best-practices/code-review/content/tested-in-dev.md

@@ -0,0 +1 @@
+# Verify that the code change has been properly tested in a development environment.

src/data/best-practices/code-review/content/trends-issues-finding.md

@@ -0,0 +1 @@
+# Hold regular code review sessions to discuss broader trends or issues that arise during the review process.

src/data/best-practices/code-review/content/update-docs-changes.md

@@ -0,0 +1 @@
+# Update any documentation that may have made obsolete through the changes.

src/data/best-practices/code-review/content/update-review-changes-docs.md

@@ -0,0 +1 @@
+# Update any documentation or code comments affected by the changes.

src/data/best-practices/code-review/content/use-automation.md

@@ -0,0 +1 @@
+# Use automation to speed up the code reviews (linting, sniffing etc)

src/data/best-practices/code-review/content/verify-changes-addressed.md

@@ -0,0 +1 @@
+# Verify that all the feedback has been addressed by the author.

src/data/best-practices/code-review/content/write-automated-tests.md

@@ -0,0 +1 @@
+# Write the automated tests.