Doc/faq

Docs/FAQ.md

@@ -0,0 +1,82 @@
+# FAQ and Issue Reporting Guidelines
+
+## Frequently Asked Questions (FAQ)
+
+### General
+
+1. **What is this project about?**  
+   This project aims to transforms how you connect with the world’s most iconic landmarks.
+
+2. **How do I get started with this project?**  
+   Refer to the [README.md](./README.md) file for step-by-step instructions to set up the project.
+
+### Common Errors and Fixes
+
+### Web
+- **Error:**   Image does not load in some places of the app.\
+  **Solution:** (temporary) use flutter run --web-renderer=html 
+  this is just a temporary fix if you want to quickly preview what the app looks like with the new changes in place in the web browser
+  (the flag --web-renderer=html is now deprecated and may not be present in future versions of flutter)
+
+#### iOS
+- **Error:**   cocoapods and pod install issues.\
+  **Solution:**
+  1. Ensure CocoaPods is installed: `sudo gem install cocoapods`.
+  2. Run `pod install` inside the iOS directory.
+
+- **Error:** App overlaps with the notification bar.  
+  **Solution:**
+  1. Modify `SafeAreaView` or update the top margin in your app layout.
+
+#### Android
+- **Error:** Gradle build fails due to incompatible Java version.  
+  **Solution:**
+  1. Ensure Java 17 is installed.
+  2. Update `build.gradle` to match the required Java version.
+
+- **Error:** Emulator not found.  
+  **Solution:**
+  1. Check your Android SDK installation path.
+  2. Verify that the `emulator` and `adb` paths are added to your `PATH` variable.
+
+#### macOS
+- **Error:** `Error: CocoaPods's specs repository is too out-of-date to satisfy dependencies.To update the CocoaPods specs, run:pod repo update Error: Error running pod install` and running pod repo update does not fix it 
+- **Solution:** 
+    1. go to macos directory delete Pods folder and Podfile.lock
+    2. run `pod install` on root of project
+    3. try to run the project using `flutter run` this should start building the macOS project 
+
+- **Error:**  An error occurred when accessing the keychain
+- **Solution:** 
+  1. you need to install xcode from apple app store 
+  2. you may need to register to apple developer account if you dont already have one
+  3. follow the video guide
+
+https://github.com/user-attachments/assets/c3b408cf-aabd-4bf3-9866-32b4982c463c
+
+- I would like to thank [Andrea Bizzotto](https://github.com/bizz84/simple_auth_flutter_firebase_ui) for his amazing blog on [Flutter & Firebase Auth on macOS: Resolving Common Issues](https://codewithandrea.com/articles/flutter-firebase-auth-macos/) which helped me solve my own issue with the project
+
+
+## How to Contribute to the FAQ
+
+1. If you encounter an issue and resolve it, consider adding it to this FAQ.
+2. To propose a change, edit this file and submit a pull request.
+3. Ensure you include:
+   - A clear problem description.
+   - Steps to reproduce the issue.
+   - Your solution or workaround.
+
+## Reporting Issues
+
+If you encounter an issue not covered here:
+
+1. **Check Existing Issues**: Before opening a new issue, search the [Issues page](./issues) to avoid duplicates.
+2. **Open a New Issue**: If no existing issue matches:
+   - Provide a descriptive title.
+   - Include a detailed description, including steps to reproduce, expected behavior, and actual behavior.
+   - Specify the environment:
+     - Operating System (e.g., macOS, Windows, Linux)
+     - Platform (e.g., iOS, Android)
+     - Node.js and npm versions (if applicable).
+3. **Use Labels**: Add relevant labels like `bug`, `enhancement`, `question`, etc.
+

Docs/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,38 @@
+## Description
+
+Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.
+
+Fixes # (issue)
+
+## Type of change
+
+Please delete options that are not relevant.
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Refactor (does not change functionality, e.g. code style improvements, linting)
+- [ ] Documentation update
+
+## How Has This Been Tested?
+
+Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration
+
+Please include screenshots below if applicable.
+
+## Checklist:
+
+- [ ] My code follows the style guidelines of this project
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+- [ ] Any dependent changes have been merged and published in downstream modules
+- [ ] I have checked my code and corrected any misspellings
+
+## Maintainer Checklist
+
+- [ ] closes #xxxx (Replace xxxx with the GitHub issue number)
+- [ ] Tag the PR with the appropriate labels

contributing.md → Docs/contributing.md

@@ -1,7 +1,7 @@
 ## Contribution Guidelines
 Please follow these practices to make it easy for the reviewers to manage the project and for the contributors to contribute.
 
-* If you fix a bug, want to implement a new feature, want to refactor the code etc,  then first open an issue, describe about the issue and then go ahead to make a MR.
+* If you fix a bug, want to implement a new feature, want to refactor the code etc,  then first open an issue, describe about the issue and then go ahead to make a MR(Merge Request).
 * If you want to work on a issue, drop in a comment on the issue thread, create a Merge Request by following the pattern ``` Fixes #<issue number> <Relevent MR title>``` and Also include ```Fixes #<issue number>``` in the description of the MR.
 * Before creating a MR, run ```flutter format lib``` in 'monumento_module' directory to format your code.
 * The merge request will not get merged until and unless there is a issue created for the same.

Docs/setup.md

@@ -0,0 +1,115 @@
+## Step 1) 🖥️ How to setup Project locally
+
+Clone the project
+
+```
+  git clone https://github.com/AOSSIE-Org/Monumento.git
+```
+
+Go to the project directory
+
+```
+  cd Monumento
+```
+
+Install dependencies
+
+```
+  flutter pub get
+```
+
+Create `.env` using template `.env.template` and add API keys
+
+```
+cat .env.template > .env
+```
+
+Add the following API keys to the `.env` file
+
+- `SERVER_CLIENT_ID`: Obtain this from the Google Cloud Console for Android configuration.
+- `GOOGLE_SIGNIN_APPLE_CLIENT_ID`: Obtain this from the Google Cloud Console for iOS configuration.
+- `GOOGLE_SIGNIN_WEB_CLIENT_ID`: Obtain this from the Google Cloud Console for web configuration.
+- `GEOAPIFY_API_KEY`: Obtain this from the [Geoapify](https://www.geoapify.com/) website for fetching location.
+
+Refer to the updated guide below for obtaining these API keys:
+
+- [Google Cloud Console Guide](https://developers.google.com/identity) for Google Sign-In or you can reffer to this [youtube video](https://www.youtube.com/watch?v=HtJKUQXmtok) where OAuth setup is done for a react app.
+- [Geoapify API Setup](https://www.geoapify.com/get-started-with-maps-api/)
+
+## Step 2) Configure Firebase
+
+Follow the official [Firebase guide](https://firebase.google.com/docs/flutter/setup?platform=android) to set it up for this project. This will:
+
+- Add the `google-services.json` file for Android.
+- Add the `GoogleService-Info.plist` file for iOS and MacOS.
+- Create the `firebase_options.dart` file in the lib folder.
+
+## Step 3)📜 Populating Monument Data
+
+This script allows you to populate your Firestore database with predefined monument data. It’s a standalone tool that you can run once to seed your database—no need to run or modify any Flutter app.
+
+### Prerequisites
+
+1. **Node.js**:
+   Install Node.js from [https://nodejs.org](https://nodejs.org).
+   Verify installation: node -v
+   You should see a version number like i.e:
+
+2. **Firebase Project with Firestore Enabled**:
+
+- Go to [Firebase Console](https://console.firebase.google.com).
+- Create or select a project.
+- Enable Firestore.
+
+3. **Service Account Key**:
+
+- In the Firebase console, go to "Project Settings" → "Service accounts".
+- Click "Generate new private key" to download `serviceAccountKey.json`.
+- Save `serviceAccountKey.json` in app root directory inside scripts folder.
+
+
+
+## **Step 4) Configure Google Sign-In (Web-Based Flutter App)**
+
+To enable Google Sign-In, follow these steps:
+
+1. **Enable Google People API**:
+   - Go to the [Google Cloud Console](https://console.cloud.google.com/).
+   - Enable the **Google People API** under the APIs & Services section.
+   - Ensure you’ve signed up for the necessary services under your project.
+
+2. **Set CORS Rules for Firebase Storage**:
+   - If you encounter a `403 Forbidden` error when attempting to load images from Firebase Storage, configure your Firebase Storage bucket to allow CORS. Refer to this guide for more details: [Handling Firebase Storage 403 Error](https://stackoverflow.com/questions/41943860/getting-403-forbidden-error-when-trying-to-load-image-from-firebase-storage).
+
+3. **Allow Access-Control-Allow-Origin**:
+   - For viewing images on the web, ensure that the Firebase Storage bucket has the appropriate `Access-Control-Allow-Origin` settings. You can follow the steps here: [Configuring Access-Control-Allow-Origin](https://stackoverflow.com/questions/37760695/firebase-storage-and-access-control-allow-origin).
+
+---
+
+4. **Install Dependencies**:
+
+- Install the Firebase Admin SDK:
+
+```
+npm install firebase-admin
+```
+
+inside scripts folder, execute the script using the following command:
+
+```
+node populate_monuments.js
+```
+
+If everything goes well, you should see:
+
+```
+Starting to populate the monuments collection...
+Monuments collection populated successfully.
+```
+
+4. **Verify in firestore**:: Check the Firebase console → Firestore Database → monuments collection. Your data should appear there.
+
+Notes:
+
+- You can rerun this script whenever you need to seed the data.
+- To add more monuments, modify the monumentsData array before running the script again.