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

feature(all): readme adaptions #739

Merged
merged 7 commits into from
Feb 7, 2024
Merged

feature(all): readme adaptions #739

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
abb869e
Added inputs from @renestalder in #707
ssandino Feb 5, 2024
2c34e56
Prettified Code!
ssandino Feb 5, 2024
70d4b80
Added troubleshooting for port taken and cleaned up some minor things
ssandino Feb 6, 2024
25f0efa
Prettified Code!
ssandino Feb 6, 2024
33e24ee
Added troubleshooting for missing translations and cleaned up
ssandino Feb 7, 2024
2292ec4
Added troubleshooting for missing translations and cleaned up
ssandino Feb 7, 2024
a83f041
Prettified Code!
ssandino Feb 7, 2024
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
163 changes: 117 additions & 46 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,16 +32,13 @@ https://user-images.githubusercontent.com/6095849/191377786-10cdb4a1-5b25-4512-a
`↗`
[Good first issues](https://github.com/socialincome-san/public/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)

2. Setup the basic development environment (see below)
3. Clone the repo and work on it
4. Make a PR and wait for review - it will be merged by team if approved
without comment
5. Your code is now merged into `main` branch and deployed on the
staging environment
([Admin Tool](https://staging-admin.socialincome.org) /
[Website](https://staging.socialincome.org/))
6. Your code is then released on the production environment with the
next release
2. Setup the basic development environment `↓`
[Setup](#basic-development-setup)
3. Clone the repo and work on it `↓` [Developing](#developing)
4. Create a PR and wait for it to be reviewed
5. If approved, the PR will be merged into the `main` branch, first on
the staging and subsequently on production `↓`
[Deployments](#deployments)

**Frontend developers:** You can also develop UI components with
[Tailwind CSS](https://tailwindcss.com) and
Expand All @@ -68,20 +65,56 @@ We are mainly leveraging the following tools:
- [Firebase Emulators](https://firebase.google.com/docs/emulator-suite)
for the local dev environment

#### 1. Install the dependencies
#### 1. Prerequisites

Make sure you are using Node.js 18. If you are using Homebrew, you can
install it with `brew install node@18` and follow
**Node.js:** `brew install node@18` (Homebrew). Make sure you are using
Node.js 18. Follow
[this](https://ralphjsmit.com/switch-between-nodejs-versions-homebrew)
guide to switch between different versions of Node.js if need be.

**java**: `brew install openjdk` (Homebrew). See also troubleshooting
below.

<details>
<summary>Troubleshooting</summary>

#### Error Missing Java

````shell
➜ socialincome-public git:(main) npm run firebase:serve

> @socialincome/[email protected] firebase:serve
> firebase emulators:start --project social-income-staging --config firebase.json --import ./seed

⚠ emulators: You are not currently authenticated so some features may not work correctly. Please run firebase login to authenticate the CLI.
i emulators: Shutting down emulators.

Error: Process `java -version` has exited with code 1. Please make sure Java is installed and on your system PATH.
-----Original stdout-----
-----Original stderr-----
The operation couldn’t be completed. Unable to locate a Java Runtime.
Please visit http://www.java.com for information on installing Java.```
````

Solution

```shell
$ brew install openjdk
$ sudo ln -sfn $HOMEBREW_PREFIX/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk
```

</details>

#### 2. Install the dependencies

```shell
npm install
```

#### 2. Start environment
#### 3. Start environment

Initiate development environments for specific tools as needed.
Initiate development environments for specific tools as needed (see
[table above](#oss-tools-by-social-income)).

- Always start the Firebase emulator first with `npm run firebase:serve`
— console dashboard is available at
Expand All @@ -94,11 +127,31 @@ Initiate development environments for specific tools as needed.
[localhost:6006](http://localhost:6006). (currently broken)

The [package.json](package.json) file gives you a good overview of the
available commands. For more information on the development environment
see table above. No production credentials are needed for local
development.
available commands.

<details>
<summary>Troubleshooting</summary>

#### Port taken

```shell
Error: Could not start Firestore Emulator, port taken.
```

Solution (macOS): In most cases it is due to port 8080 or 8085, which
can be _killed_ with one command:

```shell
kill $(lsof -t -i:8080) $(lsof -t -i:8085)
```

</details>

#### 3. Developer Logins
### Developing

#### Developer Logins

No production credentials are needed for local development.

<details>
<summary>Developer Login for Admin Tool</summary>
Expand Down Expand Up @@ -126,7 +179,7 @@ Only selected people from the SI team have access.
#### Localhost Website Login ([Link](http://localhost:3000/login))

1. Go to the [Login page](http://localhost:3000/login) and select
2. Sign in with username [email protected] and password [email protected]
2. Sign in with username [email protected] and password [email protected].

#### Staging Website Login ([Link](https://staging.socialincome.org/login))

Expand All @@ -143,62 +196,80 @@ Only actual donors have accounts and can log in. Consider making a

</details>

### Data Seed
#### Data Seed

An initial set of data is imported into the Firebase emulators during
startup of the [Admin Tool](https://staging-admin.socialincome.org). You
can add, delete or amend data directly in your local Admin Tool
([localhost:3000](http://localhost:3000)) or in your local Firestore
Admin Interface
([localhost:4000](http://localhost:4000/firestore/data)). After you have
made changes, you can export the data to the seed folder with
`npm run firebase:export`.
An initial dataset is imported into the Firebase emulators at startup.
You have the flexibility to add, delete, or modify data directly through
your [Admin Tool](http://localhost:3000) or the
[Firestore Admin Interface](http://localhost:4000/firestore/data)
locally. After making any changes, you can export the updated data to
the seed folder using the command `npm run firebase:export`.

### Format Code
#### Format Code

We are using [Prettier](https://prettier.io) to format the code:
`npm run format-code`.

```shell
npm run format-code
```

### Deployments
#### Deployments

**Staging deployments:** PRs merged into `main` are automatically
deployed to staging
([Admin Tool](https://staging-admin.socialincome.org) /
**Staging:** PRs merged into `main` are automatically deployed to
staging ([Admin Tool](https://staging-admin.socialincome.org) /
[Website](https://staging.socialincome.org/)) upon core developer
approval. Check [Github Actions](./.github/workflows) for details.
Experienced contributors can deploy directly
[without approval](mailto:[email protected]).

**Production deployments:** Deployments are made by core developers via
**Production:** Deployments are made by core developers via
[GitHub releases](https://github.com/socialincome-san/public/actions/workflows/production-deployment.yml).
Use "release-YYYY-MM-DD" for the release name
(example:`release-2021-02-27`). For multiple releases on the same day,
append ".2", ".3", etc. (example:`release-2021-02-27.2`).

### Backups
<details>
<summary>Naming Convention</summary>

Use the format "release-YYYY-MM-DD" for naming releases (example:
`release-2021-02-27`). For multiple releases on the same day, append a
suffix such as ".2", ".3", and so forth, to distinguish them (example:
`release-2021-02-27.2`).

</details>

#### Backups

We have a
[function](https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_function%22%20resource.labels.function_name%3D%22siWebFirestoreExport%22%20resource.labels.region%3D%22us-central1%22?project=social-income-prod&authuser=1&hl=en)
which triggers hourly backups of our production firestore database. The
exports are saved to the
[social-income-prod](https://console.cloud.google.com/storage/browser/social-income-prod;tab=objects?forceOnBucketsSortingFiltering=false&authuser=1&project=social-income-prod&prefix=&forceOnObjectsSortingFiltering=true)
bucket with a retention period of 30 days. To restore the database you
can
bucket with a retention period of 30 days.

<details>
<summary>Restore Database</summary>

To restore the database you can
[import](https://console.cloud.google.com/firestore/import-export?authuser=1&project=social-income-prod)
the most recent folder directly from the
[social-income-prod](https://console.cloud.google.com/storage/browser/social-income-prod;tab=objects?forceOnBucketsSortingFiltering=false&authuser=1&project=social-income-prod&prefix=&forceOnObjectsSortingFiltering=true)
bucket.

### Bugs & Feature Requests
</details>

#### Bugs & Feature Requests

You can report an issue or request a feature on our
[issue page](https://github.com/socialincome-san/public/issues/new/choose).
If you want to report a vulnareablity please refer to our
[security policy](https://github.com/socialincome-san/public/blob/main/SECURITY.md).

<details>
<summary>Troubleshooting Development</summary>

**Problem**: Added or amended translations do not appear in the
localhost preview.

**Solution**: Remove the `website/.next` folder, which is automatically
generated, then re-execute `npm run website:serve`.

</details>

# Financial Contributions

### Donate 1 Percent of Your Income
Expand Down
Loading