Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added pages #3049

Merged
merged 1 commit into from
Jan 27, 2025
Merged

Added pages #3049

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions docs/docs/docs/developer-resources/operation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
---
id: operation
title: Operation
slug: /developer-resources/operation
sidebar_position: 3
---

## Operation

This section covers how Talawa API operates

Comment on lines +8 to +11
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Improve the introduction section.

The current introduction is too brief and doesn't provide a clear overview of what readers will learn. Consider expanding it to outline the key topics covered in this document.

 ## Operation

-This section covers how Talawa API operates
+This document explains how to work with the Talawa API development environment, focusing on:
+
+- Development container setup and configuration
+- Service dependencies and their roles
+- Environment configuration
+- Startup sequence and troubleshooting
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## Operation
This section covers how Talawa API operates
## Operation
This document explains how to work with the Talawa API development environment, focusing on:
- Development container setup and configuration
- Service dependencies and their roles
- Environment configuration
- Startup sequence and troubleshooting

### Key Concepts

Before you begin, here are some important summaries of the technologies used.

#### Docker Development Containers (devcontainers)

Talawa API uses devcontainers for many features

Development containers, or devcontainers, are Docker containers that are specifically configured to provide a fully featured development environment. They can be used to run an application, to separate tools, libraries, or runtimes needed for working with a codebase, and to aid in continuous integration and testing. Dev containers can be run locally or remotely, in a private or public cloud, in a variety of supporting tools and editors.

The Development Container Specification seeks to find ways to enrich existing formats with common development specific settings, tools, and configuration while still providing a simplified, un-orchestrated single container option – so that they can be used as coding environments or for continuous integration and testing. Beyond the specification's core metadata, the spec also enables developers to quickly share and reuse container setup steps through Features and Templates.

Comment on lines +18 to +23
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Enhance the devcontainers explanation.

The explanation of devcontainers could be more structured and technically precise.

-Talawa API uses devcontainers for many features
+Talawa API uses Development Containers (devcontainers) to provide:
+
+- Consistent development environments across the team
+- Isolated runtime dependencies
+- Integrated development and debugging experience
+- Automated environment setup

 Development containers, or devcontainers, are Docker containers that are specifically configured to provide a fully featured development environment. They can be used to run an application, to separate tools, libraries, or runtimes needed for working with a codebase, and to aid in continuous integration and testing. Dev containers can be run locally or remotely, in a private or public cloud, in a variety of supporting tools and editors.

-The Development Container Specification seeks to find ways to enrich existing formats with common development specific settings, tools, and configuration while still providing a simplified, un-orchestrated single container option – so that they can be used as coding environments or for continuous integration and testing. Beyond the specification's core metadata, the spec also enables developers to quickly share and reuse container setup steps through Features and Templates.
+The Development Container Specification enriches existing container formats with development-specific settings while maintaining simplicity. This enables:
+
+- Consistent coding environments
+- Simplified continuous integration
+- Reusable container configurations through Features and Templates
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Talawa API uses devcontainers for many features
Development containers, or devcontainers, are Docker containers that are specifically configured to provide a fully featured development environment. They can be used to run an application, to separate tools, libraries, or runtimes needed for working with a codebase, and to aid in continuous integration and testing. Dev containers can be run locally or remotely, in a private or public cloud, in a variety of supporting tools and editors.
The Development Container Specification seeks to find ways to enrich existing formats with common development specific settings, tools, and configuration while still providing a simplified, un-orchestrated single container option – so that they can be used as coding environments or for continuous integration and testing. Beyond the specification's core metadata, the spec also enables developers to quickly share and reuse container setup steps through Features and Templates.
Talawa API uses Development Containers (devcontainers) to provide:
- Consistent development environments across the team
- Isolated runtime dependencies
- Integrated development and debugging experience
- Automated environment setup
Development containers, or devcontainers, are Docker containers that are specifically configured to provide a fully featured development environment. They can be used to run an application, to separate tools, libraries, or runtimes needed for working with a codebase, and to aid in continuous integration and testing. Dev containers can be run locally or remotely, in a private or public cloud, in a variety of supporting tools and editors.
The Development Container Specification enriches existing container formats with development-specific settings while maintaining simplicity. This enables:
- Consistent coding environments
- Simplified continuous integration
- Reusable container configurations through Features and Templates
🧰 Tools
🪛 LanguageTool

[style] ~20-~20: The phrase “a variety of” may be wordy. To make your writing clearer, consider replacing it.
Context: ...otely, in a private or public cloud, in a variety of supporting tools and editors. The Deve...

(A_VARIETY_OF)

[style] ~22-~22: This phrase is redundant. Consider writing “seeks”.
Context: ...The Development Container Specification seeks to find ways to enrich existing formats with co...

(SEEK_TO_FIND)

[uncategorized] ~22-~22: When ‘development-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ... to enrich existing formats with common development specific settings, tools, and configuration whil...

(SPECIFIC_HYPHEN)

- For more information visit [containers.dev](https://containers.dev/)

Regular Docker's core features are contrary to using it as a developer environment.

1. Each container has an isolated filesystem, so the container can't normally see code on the host system, and the host system can't see tools that are only installed in the container.
2. A container is based on an immutable image: you can't normally change the code a container is running without rebuilding the image and recreating the container. This is a familiar workflow for developers using compiled languages (C++, Java, Go, Rust), where even without Docker you still need to recompile and restart the application after every change.

Visit [this link](https://stackoverflow.com/questions/75652065/whats-the-difference-between-docker-compose-and-dev-containers) for further information on the differences between Containers and Dev Containers.

##### Talawa API Dev Containers

In Talawa API, the API devcontainer operates like a lightweight virtual machine which has network access available to the external containers services including:

1. `postgres`
1. `postgres-test`
1. `minio`
1. `minio-test`
1. `cloudbeaver`
1. `caddy`

The Talawa API git repository is mounted on it. After the Dev Container starts, the `node.js` development server runs on a port mapped to a port on your host system.

The API runs by default when the devcontainer starts, but only after the these compose services have already started.

Comment on lines +46 to +47
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Fix grammar in the startup description.

There's a grammatical error in the sentence.

-The API runs by default when the devcontainer starts, but only after the these compose services have already started.
+The API runs by default when the devcontainer starts, but only after these compose services have already started.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
The API runs by default when the devcontainer starts, but only after the these compose services have already started.
The API runs by default when the devcontainer starts, but only after these compose services have already started.

**IMPORTANT NOTES**

1. Always keep your code up to date in your local branch because there may be changes not just to the code, but to the devcontainer configuration.
1. Make sure your `.env` file is up to date with the latest changes in `.env.devcontainer` and restart the containers when there are changes.
2. A `.env` file will be automatically created when the devcontainer starts, if doesn't previously exist.
3. Preexisting `.env` files are not automatically updated with remote changes, you have to do that yourself.
2. Healthchecks are skipped in the devcontainer, because if the healthcheck for it was running then the api devcontainer would never start.
Comment on lines +48 to +54
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Restructure the important notes section.

Convert the emphasis to a proper heading and improve the formatting of notes.

-**IMPORTANT NOTES**
+### Important Notes
 
-1. Always keep your code up to date in your local branch because there may be changes not just to the code, but to the devcontainer configuration.
-   1. Make sure your `.env` file is up to date with the latest changes in `.env.devcontainer` and restart the containers when there are changes.
-   2. A `.env` file will be automatically created when the devcontainer starts, if doesn't previously exist.
-   3. Preexisting `.env` files are not automatically updated with remote changes, you have to do that yourself.
-2. Healthchecks are skipped in the devcontainer, because if the healthcheck for it was running then the api devcontainer would never start.
+#### Code and Configuration Management
+
+- Keep your local branch up-to-date with remote changes, including both code and devcontainer configuration
+
+#### Environment Variables
+
+- Keep your `.env` file in sync with `.env.devcontainer`
+- Restart containers after updating environment variables
+- New installations automatically create `.env` file
+- Existing `.env` files must be manually updated
+
+#### Health Checks
+
+- Healthchecks are skipped in the devcontainer to prevent startup issues
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
**IMPORTANT NOTES**
1. Always keep your code up to date in your local branch because there may be changes not just to the code, but to the devcontainer configuration.
1. Make sure your `.env` file is up to date with the latest changes in `.env.devcontainer` and restart the containers when there are changes.
2. A `.env` file will be automatically created when the devcontainer starts, if doesn't previously exist.
3. Preexisting `.env` files are not automatically updated with remote changes, you have to do that yourself.
2. Healthchecks are skipped in the devcontainer, because if the healthcheck for it was running then the api devcontainer would never start.
### Important Notes
#### Code and Configuration Management
- Keep your local branch up-to-date with remote changes, including both code and devcontainer configuration
#### Environment Variables
- Keep your `.env` file in sync with `.env.devcontainer`
- Restart containers after updating environment variables
- New installations automatically create `.env` file
- Existing `.env` files must be manually updated
#### Health Checks
- Healthchecks are skipped in the devcontainer to prevent startup issues
🧰 Tools
🪛 LanguageTool

[uncategorized] ~51-~51: It appears that hyphens are missing in the adjective “up-to-date”.
Context: ...on. 1. Make sure your .env file is up to date with the latest changes in `.env.devcon...

(UP_TO_DATE_HYPHEN)

[typographical] ~52-~52: Usually, there’s no comma before “if”.
Context: ...lly created when the devcontainer starts, if doesn't previously exist. 3. Preexis...

(IF_NO_COMMA)

[formatting] ~54-~54: If the ‘because’ clause is essential to the meaning, do not use a comma before the clause.
Context: ...thchecks are skipped in the devcontainer, because if the healthcheck for it was running t...

(COMMA_BEFORE_BECAUSE)

🪛 markdownlint-cli2 (0.17.2)

48-48: Emphasis used instead of a heading
null

(MD036, no-emphasis-as-heading)


### Startup Sequence

## Troubleshooting
Comment on lines +56 to +58
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

⚠️ Potential issue

Add content to empty sections.

The "Startup Sequence" and "Troubleshooting" sections are empty. These are crucial sections for developers.

Would you like me to help draft content for these sections? The startup sequence should detail the order of services initialization, and troubleshooting should cover common issues and their solutions.

10 changes: 10 additions & 0 deletions docs/docs/docs/developer-resources/testing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
id: testing
title: Testing
slug: /developer-resources/testing
sidebar_position: 4
---

## Introduction

Coming soon.
Comment on lines +8 to +10
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

⚠️ Potential issue

Testing documentation needs essential content.

The "Coming soon" placeholder should be replaced with comprehensive testing documentation to help contributors understand how to:

  • Set up the testing environment
  • Run different types of tests (unit, integration, e2e)
  • Write new tests
  • Debug failing tests
  • View test coverage reports

Would you like me to help draft a detailed testing documentation structure with these essential sections?

56 changes: 4 additions & 52 deletions docs/docs/docs/developer-resources/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,58 +1,10 @@
---
id: troubleshooting
title: Operation & Troubleshooting
title: Operation
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Resolve inconsistency between file name and content.

The file is named "troubleshooting.md" but the title and content are about "Operation". This inconsistency could confuse users and impact documentation navigation. Consider either:

  1. Keeping troubleshooting content in this file and moving operation content to operation.md, or
  2. Renaming this file to operation.md and updating all references accordingly

Also applies to: 8-10

slug: /developer-resources/troubleshooting
sidebar_position: 3
sidebar_position: 5
Comment on lines +3 to +5
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codebase verification

Update slug to match the new "Operation" title

The file's title has been changed to "Operation" but the slug still points to "/developer-resources/troubleshooting". While no external links to this path were found, the slug should be updated to "/developer-resources/operation" for consistency with the new title and to avoid future confusion.

🔗 Analysis chain

Verify documentation links integrity.

The changes in title and sidebar position, combined with content removal, might have broken existing documentation links.

Let's verify the impact:

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Search for any references to the old troubleshooting page
echo "Searching for references to troubleshooting in markdown files..."
rg -t md "(?i)(troubleshooting|operation.*troubleshooting)" docs/

# Search for sidebar navigation references
echo "Checking sidebar navigation configuration..."
find docs/ -name "sidebars.js" -exec cat {} \;

Length of output: 702

Script:

#!/bin/bash
# Check if sidebars.js exists and its location
echo "Locating sidebars.js..."
fd sidebars.js

# Check content of operation.md
echo -e "\nChecking operation.md content..."
cat docs/docs/docs/developer-resources/operation.md

# Search for direct links to troubleshooting path
echo -e "\nSearching for direct links..."
rg -t md "/developer-resources/troubleshooting" docs/

Length of output: 3907

---

## Operation
## Introduction

This section covers how Talawa API operates

### Key Concepts

Before you begin, here are some important summaries of the technologies used.

#### Docker Development Containers (devcontainers)

Talawa API uses devcontainers for many features

Development containers, or devcontainers, are Docker containers that are specifically configured to provide a fully featured development environment. They can be used to run an application, to separate tools, libraries, or runtimes needed for working with a codebase, and to aid in continuous integration and testing. Dev containers can be run locally or remotely, in a private or public cloud, in a variety of supporting tools and editors.

The Development Container Specification seeks to find ways to enrich existing formats with common development specific settings, tools, and configuration while still providing a simplified, un-orchestrated single container option – so that they can be used as coding environments or for continuous integration and testing. Beyond the specification's core metadata, the spec also enables developers to quickly share and reuse container setup steps through Features and Templates.

- For more information visit [containers.dev](https://containers.dev/)

Regular Docker's core features are contrary to using it as a developer environment.

1. Each container has an isolated filesystem, so the container can't normally see code on the host system, and the host system can't see tools that are only installed in the container.
2. A container is based on an immutable image: you can't normally change the code a container is running without rebuilding the image and recreating the container. This is a familiar workflow for developers using compiled languages (C++, Java, Go, Rust), where even without Docker you still need to recompile and restart the application after every change.

Visit [this link](https://stackoverflow.com/questions/75652065/whats-the-difference-between-docker-compose-and-dev-containers) for further information on the differences between Containers and Dev Containers.

##### Talawa API Dev Containers

In Talawa API, the API devcontainer operates like a lightweight virtual machine which has network access available to the external containers services including:

1. `postgres`
1. `postgres-test`
1. `minio`
1. `minio-test`
1. `cloudbeaver`
1. `caddy`

The Talawa API git repository is mounted on it. After the Dev Container starts, the `node.js` development server runs on a port mapped to a port on your host system.

The API runs by default when the devcontainer starts, but only after the these compose services have already started.

**IMPORTANT NOTES**

1. Always keep your code up to date in your local branch because there may be changes not just to the code, but to the devcontainer configuration.
1. Make sure your `.env` file is up to date with the latest changes in `.env.devcontainer` and restart the containers when there are changes.
2. A `.env` file will be automatically created when the devcontainer starts, if doesn't previously exist.
3. Preexisting `.env` files are not automatically updated with remote changes, you have to do that yourself.
2. Healthchecks are skipped in the devcontainer, because if the healthcheck for it was running then the api devcontainer would never start.

### Startup Sequence

## Troubleshooting
Coming soon.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Add a migration notice for users.

Instead of just "Coming soon", provide a temporary notice directing users to where they can find the moved content. For example:

-Coming soon.
+> **Note:** The operation documentation has been moved to the new [Operation guide](../operation). The troubleshooting guide will be updated soon.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Coming soon.
> **Note:** The operation documentation has been moved to the new [Operation guide](../operation). The troubleshooting guide will be updated soon.

Loading