Skip to content

Commit 7d20365

Browse files
mdmohsin7mdmohsin7
authored
Merge pull request #241 from HelloSniperMonkey/doc/faq
Doc/faq
2 parents 933873d + 8d646cf commit 7d20365

File tree

5 files changed

+252
-127
lines changed

5 files changed

+252
-127
lines changed

‎Docs/FAQ.md

+82
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# FAQ and Issue Reporting Guidelines
2+
3+
## Frequently Asked Questions (FAQ)
4+
5+
### General
6+
7+
1. **What is this project about?**
8+
This project aims to transforms how you connect with the world’s most iconic landmarks.
9+
10+
2. **How do I get started with this project?**
11+
Refer to the [README.md](./README.md) file for step-by-step instructions to set up the project.
12+
13+
### Common Errors and Fixes
14+
15+
### Web
16+
- **Error:** Image does not load in some places of the app.\
17+
**Solution:** (temporary) use flutter run --web-renderer=html
18+
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
19+
(the flag --web-renderer=html is now deprecated and may not be present in future versions of flutter)
20+
21+
#### iOS
22+
- **Error:** cocoapods and pod install issues.\
23+
**Solution:**
24+
1. Ensure CocoaPods is installed: `sudo gem install cocoapods`.
25+
2. Run `pod install` inside the iOS directory.
26+
27+
- **Error:** App overlaps with the notification bar.
28+
**Solution:**
29+
1. Modify `SafeAreaView` or update the top margin in your app layout.
30+
31+
#### Android
32+
- **Error:** Gradle build fails due to incompatible Java version.
33+
**Solution:**
34+
1. Ensure Java 17 is installed.
35+
2. Update `build.gradle` to match the required Java version.
36+
37+
- **Error:** Emulator not found.
38+
**Solution:**
39+
1. Check your Android SDK installation path.
40+
2. Verify that the `emulator` and `adb` paths are added to your `PATH` variable.
41+
42+
#### macOS
43+
- **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
44+
- **Solution:**
45+
1. go to macos directory delete Pods folder and Podfile.lock
46+
2. run `pod install` on root of project
47+
3. try to run the project using `flutter run` this should start building the macOS project
48+
49+
- **Error:** An error occurred when accessing the keychain
50+
- **Solution:**
51+
1. you need to install xcode from apple app store
52+
2. you may need to register to apple developer account if you dont already have one
53+
3. follow the video guide
54+
55+
https://github.com/user-attachments/assets/c3b408cf-aabd-4bf3-9866-32b4982c463c
56+
57+
- 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
58+
59+
60+
## How to Contribute to the FAQ
61+
62+
1. If you encounter an issue and resolve it, consider adding it to this FAQ.
63+
2. To propose a change, edit this file and submit a pull request.
64+
3. Ensure you include:
65+
- A clear problem description.
66+
- Steps to reproduce the issue.
67+
- Your solution or workaround.
68+
69+
## Reporting Issues
70+
71+
If you encounter an issue not covered here:
72+
73+
1. **Check Existing Issues**: Before opening a new issue, search the [Issues page](./issues) to avoid duplicates.
74+
2. **Open a New Issue**: If no existing issue matches:
75+
- Provide a descriptive title.
76+
- Include a detailed description, including steps to reproduce, expected behavior, and actual behavior.
77+
- Specify the environment:
78+
- Operating System (e.g., macOS, Windows, Linux)
79+
- Platform (e.g., iOS, Android)
80+
- Node.js and npm versions (if applicable).
81+
3. **Use Labels**: Add relevant labels like `bug`, `enhancement`, `question`, etc.
82+

‎Docs/PULL_REQUEST_TEMPLATE.md

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
## Description
2+
3+
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.
4+
5+
Fixes # (issue)
6+
7+
## Type of change
8+
9+
Please delete options that are not relevant.
10+
11+
- [ ] Bug fix (non-breaking change which fixes an issue)
12+
- [ ] New feature (non-breaking change which adds functionality)
13+
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
14+
- [ ] Refactor (does not change functionality, e.g. code style improvements, linting)
15+
- [ ] Documentation update
16+
17+
## How Has This Been Tested?
18+
19+
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
20+
21+
Please include screenshots below if applicable.
22+
23+
## Checklist:
24+
25+
- [ ] My code follows the style guidelines of this project
26+
- [ ] I have performed a self-review of my own code
27+
- [ ] I have commented my code, particularly in hard-to-understand areas
28+
- [ ] I have made corresponding changes to the documentation
29+
- [ ] My changes generate no new warnings
30+
- [ ] I have added tests that prove my fix is effective or that my feature works
31+
- [ ] New and existing unit tests pass locally with my changes
32+
- [ ] Any dependent changes have been merged and published in downstream modules
33+
- [ ] I have checked my code and corrected any misspellings
34+
35+
## Maintainer Checklist
36+
37+
- [ ] closes #xxxx (Replace xxxx with the GitHub issue number)
38+
- [ ] Tag the PR with the appropriate labels

‎contributing.md ‎Docs/contributing.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
## Contribution Guidelines
22
Please follow these practices to make it easy for the reviewers to manage the project and for the contributors to contribute.
33

4-
* 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.
4+
* 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).
55
* 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.
66
* Before creating a MR, run ```flutter format lib``` in 'monumento_module' directory to format your code.
77
* The merge request will not get merged until and unless there is a issue created for the same.

‎Docs/setup.md

+115
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
## Step 1) 🖥️ How to setup Project locally
2+
3+
Clone the project
4+
5+
```
6+
git clone https://github.com/AOSSIE-Org/Monumento.git
7+
```
8+
9+
Go to the project directory
10+
11+
```
12+
cd Monumento
13+
```
14+
15+
Install dependencies
16+
17+
```
18+
flutter pub get
19+
```
20+
21+
Create `.env` using template `.env.template` and add API keys
22+
23+
```
24+
cat .env.template > .env
25+
```
26+
27+
Add the following API keys to the `.env` file
28+
29+
- `SERVER_CLIENT_ID`: Obtain this from the Google Cloud Console for Android configuration.
30+
- `GOOGLE_SIGNIN_APPLE_CLIENT_ID`: Obtain this from the Google Cloud Console for iOS configuration.
31+
- `GOOGLE_SIGNIN_WEB_CLIENT_ID`: Obtain this from the Google Cloud Console for web configuration.
32+
- `GEOAPIFY_API_KEY`: Obtain this from the [Geoapify](https://www.geoapify.com/) website for fetching location.
33+
34+
Refer to the updated guide below for obtaining these API keys:
35+
36+
- [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.
37+
- [Geoapify API Setup](https://www.geoapify.com/get-started-with-maps-api/)
38+
39+
## Step 2) Configure Firebase
40+
41+
Follow the official [Firebase guide](https://firebase.google.com/docs/flutter/setup?platform=android) to set it up for this project. This will:
42+
43+
- Add the `google-services.json` file for Android.
44+
- Add the `GoogleService-Info.plist` file for iOS and MacOS.
45+
- Create the `firebase_options.dart` file in the lib folder.
46+
47+
## Step 3)📜 Populating Monument Data
48+
49+
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.
50+
51+
### Prerequisites
52+
53+
1. **Node.js**:
54+
Install Node.js from [https://nodejs.org](https://nodejs.org).
55+
Verify installation: node -v
56+
You should see a version number like i.e:
57+
58+
2. **Firebase Project with Firestore Enabled**:
59+
60+
- Go to [Firebase Console](https://console.firebase.google.com).
61+
- Create or select a project.
62+
- Enable Firestore.
63+
64+
3. **Service Account Key**:
65+
66+
- In the Firebase console, go to "Project Settings" → "Service accounts".
67+
- Click "Generate new private key" to download `serviceAccountKey.json`.
68+
- Save `serviceAccountKey.json` in app root directory inside scripts folder.
69+
70+
71+
72+
## **Step 4) Configure Google Sign-In (Web-Based Flutter App)**
73+
74+
To enable Google Sign-In, follow these steps:
75+
76+
1. **Enable Google People API**:
77+
- Go to the [Google Cloud Console](https://console.cloud.google.com/).
78+
- Enable the **Google People API** under the APIs & Services section.
79+
- Ensure you’ve signed up for the necessary services under your project.
80+
81+
2. **Set CORS Rules for Firebase Storage**:
82+
- 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).
83+
84+
3. **Allow Access-Control-Allow-Origin**:
85+
- 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).
86+
87+
---
88+
89+
4. **Install Dependencies**:
90+
91+
- Install the Firebase Admin SDK:
92+
93+
```
94+
npm install firebase-admin
95+
```
96+
97+
inside scripts folder, execute the script using the following command:
98+
99+
```
100+
node populate_monuments.js
101+
```
102+
103+
If everything goes well, you should see:
104+
105+
```
106+
Starting to populate the monuments collection...
107+
Monuments collection populated successfully.
108+
```
109+
110+
4. **Verify in firestore**:: Check the Firebase console → Firestore Database → monuments collection. Your data should appear there.
111+
112+
Notes:
113+
114+
- You can rerun this script whenever you need to seed the data.
115+
- To add more monuments, modify the monumentsData array before running the script again.

0 commit comments

Comments
 (0)