From a0bcd102f906a78f498968aee2fafc2469ebb502 Mon Sep 17 00:00:00 2001
From: Rajitha Gunathilake <38534289+RizkyRajitha@users.noreply.github.com>
Date: Tue, 21 Sep 2021 11:07:56 +0530
Subject: [PATCH] Create CONTRIBUTING.md
---
CONTRIBUTING.md | 280 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 280 insertions(+)
create mode 100644 CONTRIBUTING.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..e968215
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,280 @@
+# Contributing
+
+Welcome to Linkin contribution guidelines. Linkin highly appreciates your support making it better in any order of magnitude.
+
+## Code of Conduct
+
+Help us keep Linkin open and inclusive. Please read and follow our [Code of Conduct](/CODE_OF_CONDUCT.md).
+
+## Community
+
+If you any clarifications or any feedback on Linkin please reach on discord https://discord.gg/Jsmc5Dm9wg
+
+## Linkin Build with
+
+- [Next.Js](https://nextjs.org/)
+- [Postgres](https://www.postgresql.org/)
+- [Prisma](https://www.prisma.io/)
+- [Bootstrap](https://getbootstrap.com/)
+
+## Developing locally
+
+#### Requirements
+
+- Node.js 12.x or newer
+- Postgresql database (docker or otherwise)
+
+#### Clone and install dependencies
+
+```bash
+git clone https://github.com/RizkyRajitha/linkin.git
+cd linkin
+npm i
+```
+
+
+
+Setup local environment variables in `.env`
+
+example `.env` file
+
+```
+DATABASE_URL=postgres://linkin:123@localhost:5432/linkin
+HASHSALT=123
+```
+
+#### Database migration
+
+create database relations with prisma migration. please refer to [prisma documentation](https://www.prisma.io/docs/concepts/components/prisma-migrate) for further migration info (`npx prisma migrate dev` you will need permission to create databases if such problem occurs use docker Postgres instance ).
+
+**you must have Postgres database setup locally**
+
+```bash
+npx prisma migrate dev
+```
+
+#### Database Seeding
+
+Adding initial data to the database to get you started
+
+```bash
+npm run seed
+```
+
+#### Run
+
+```
+npm run dev
+```
+
+## Branching Strategy
+
+Linkin has 2 main branches
+
+1. [master](https://github.com/RizkyRajitha/linkin/tree/master) branch - will have the code from the latest release. only updates on a release.
+2. [dev](https://github.com/RizkyRajitha/linkin/tree/dev) branch - all the development carries out in this branch. the latest code will be available in this branch, **all the pull requests should be made to dev branch** since prs could be tested and modified for the final release phase.
+
+other than the above branches there can feature specific branches for the continence.
+
+## File Structure
+
+```
+├── app.json
+| (React components)
+├── components
+│ ├── alert.js
+│ ├── colorform.js
+│ ├── context
+│ │ └── state.js
+│ ├── fontform.js
+│ ├── footerform.js
+│ ├── formwrapper.js
+│ ├── genaralform.js
+│ ├── linkcard.js
+│ ├── linkinthebiopage.js
+│ ├── linksform.js
+│ ├── passwordchangeform.js
+│ └── toast.js
+├── configs
+│ └── config.js
+├── CONTRIBUTING.md
+| (Database connection)
+├── db
+│ └── dbconprisma.js
+├── docker-compose.yml
+├── Dockerfile
+├── hashgen.js
+├── jest.config.js
+| (Lib for all the database operations , and utilities)
+├── lib
+│ ├── crypto.js
+│ ├── dbfuncprisma.js
+│ └── side.js
+├── LICENSE
+├── loadtest.sh
+| (all the API middlewares)
+├── middleware
+│ └── middleware.js
+├── next.config.js
+├── package.json
+├── package-lock.json
+| (Nextjs pages , APIs)
+├── pages
+│ ├── admin.js
+│ ├── api
+│ │ ├── changepassword.js
+│ │ ├── deletepagelink.js
+│ │ ├── insertpagelinks.js
+│ │ ├── login.js
+│ │ ├── logout.js
+│ │ ├── reorderlinks.js
+│ │ ├── updatepagedata.js
+│ │ ├── updatepagelinks.js
+│ │ └── view.js
+│ ├── _app.js
+│ ├── dashboard.js
+│ └── index.js
+| (Prisma migrations and schemas)
+├── prisma
+│ ├── migrations
+│ │ ├── 20210701133353_init
+│ │ │ └── migration.sql
+│ │ ├── 20210701134107_added_text_color_attribute
+│ │ │ └── migration.sql
+│ │ ├── 20210703151237_add_footer_data
+│ │ │ └── migration.sql
+│ │ ├── 20210707070241_add_description_feild
+│ │ │ └── migration.sql
+│ │ ├── 20210707070312_add_accent_color_to_link
+│ │ │ └── migration.sql
+│ │ ├── 20210707095411_add_footer_enable
+│ │ │ └── migration.sql
+│ │ ├── 20210707111847_add_link_borderradius
+│ │ │ └── migration.sql
+│ │ ├── 20210729134704_add_reorder_links
+│ │ │ └── migration.sql
+│ │ ├── 20210917091814_added_avatar_border_color
+│ │ │ └── migration.sql
+│ │ └── migration_lock.toml
+│ └── schema.prisma
+├── Procfile
+├── public
+│ ├── favicon.ico
+│ ├── fontawesome
+│ ├── images
+│ │ ├── avatar.jpg
+│ │ ├── keiraknightley400.png
+│ │ └── logo.jpg
+│ ├── vercel.svg
+│ └── webfonts
+├── railwaymigrate.sh
+├── README.md
+| (scripts for seeding , db-migrate.sql , db-migrate-test.sql is out-dated and soon will be removed)
+├── scripts
+│ ├── db-migrate.sql
+│ ├── db-migrate-test.sql
+│ └── seed.js
+| (css styles for react components)
+├── styles
+│ ├── boostrap.min.css
+│ ├── dashboard.module.css
+│ ├── form.module.css
+│ ├── formwrapper.module.css
+│ ├── global.css
+│ ├── homeview.module.css
+│ ├── landing.module.css
+│ ├── login.module.css
+│ └── utils.module.css
+| (test cases for database operations)
+└── __tests__
+ ├── prismalinkdata.test.js
+ ├── prismapagedata.test.js
+ ├── prismausers.test.js
+ └── side.test.js
+```
+
+## Frontend components layout
+
+Frontend consists of 3 main components
+
+1. admin page `/admin`
+
+2. dashboard `/dashboard`
+
+3. index page (actual link tree) `/`
+
+### admin page
+
+admin page is the login page for the admin. it will `post` the login credentials to the API and validated the user.
+
+![admin page](https://res.cloudinary.com/dijjqfsto/image/upload/v1632202406/linkin/Screenshot_2021-09-20_at_15-52-18_Admin_Login_slb6lo.png)
+
+### dashboard page
+
+the dashboard allows user to modify their link tree appearance.
+
+it has 3 main parts
+
+1. Formwrapper
+2. Forms
+3. preview
+
+![dashboard page](https://res.cloudinary.com/dijjqfsto/image/upload/v1632202406/linkin/Untitled_Diagram.drawio_l2rkop.png)
+
+#### Formwrapper
+
+Formwrapper is the wrapper element around the actual forms. this component will conditionally render the inner forms based on the selected form.
+it is responsible for the data inserting and updating that the inner forms submit. this wrapper holds the toast container for the toast messages.
+
+#### Forms
+
+there are 6 forms inside the `Formwrapper`.form has been divided into this manner to make every form more specific to the use case, and also making the navigation possible.
+
+1. General Details (a form that holds general details) [genaralform.js](./components/genaralform.js)
+2. Footer Details (a form that holds footer details) [footerform.js](./components/footerform.js)
+3. Colors (form that holds color details) [colorform.js](./components/colorform.js)
+4. Fonts (form that holds font details) [fontform.js](./components/fontform.js)
+5. Link Data (a form that configures links and their respective details, this form have it's how API posing to facilitate live refresh in links) [linksform.js](./components/linksform.js)
+6. Updated Password (a form that updates the password) [passwordchangeform.js](./components/passwordchangeform.js)
+
+#### Preview
+
+This component updates (real-time on links form) based on the form data modifications. this is [linkinthebiopage.js](./components/linkinthebiopage.js), the same component that is rendered in the `index` page but with less width.
+
+### index page
+
+the linkin tree component that is visible to the users.
+
+![index page](https://res.cloudinary.com/dijjqfsto/image/upload/v1632202539/linkin/Screenshot_2021-09-21_at_11-05-24_LinkIn_s_Link_tree_Page_isgsez.png)
+
+## API
+
+Linkin levarages next js built-in [api-routes](https://nextjs.org/docs/api-routes/introduction).
+this removes the requirement of additional API deployment, making Linkin cleaner and easier to deploy.
+all the API routes live in [/pages/api/](./pages/api/) directory.
+
+Linkin has 8 API routes
+
+1. login [login.js](./pages/api/login.js)
+2. logout [logout.js](./pages/api/logout.js)
+3. changepassword [changepassword.js](./pages/api/changepassword.js)
+4. updatepagedata [updatepagedata.js](./pages/api/updatepagedata.js)
+5. insertpagelinks [insertpagelinks.js](./pages/api/insertpagelinks.js)
+6. updatepagelinks [updatepagelinks.js](./pages/api/updatepagelinks.js)
+7. deletepagelink [deletepagelink.js](./pages/api/deletepagelink.js)
+8. reorderlinks [reorderlinks.js](./pages/api/reorderlinks.js)
+
+| API | method | data | response |
+| --------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| login | post | `{username: "username",password: "password"}` | `200` `{ success : true }`
`401` invalid_credential
`500` errasasasasassasor |
+| logout | get | | `200` `{ success : true , message : "logout" }` |
+| changepassword | post | `{currentPassword: "password", newPassword: "newpassword"}` | `200` `{ success : true }`
`500` error |
+| updatepagedata | post | `{"id":1,...}` | `400` method not allowed
`200` `{ success: true, updatedPageData:{...}}`
`500` `{ success: false, message: "error.message" }` |
+| insertpagelinks | post | {...} | `400` method not allowed
`200` `{ success: true, updatedLinkData:{...}}`
`500` `{ success: false, message: "error.message" }` |
+| updatepagelinks | post | `{"id":1,...}` | `400` method not allowed
`200` `{ success: true, updatedLinkData:{...}}`
`500` `{ success: false, message: "error.message" }` |
+| deletepagelink | post | {id:"1"} | `400` method not allowed
`200` `{ success: true }`
`500` `{ success: false, message: "error.message" }` |
+| reorderlinks | post | `{"orderData":[{"id":3,"name":"","orderIndex":0},{"id":1,"name":"","orderIndex":1},{"id":2,"name":"","orderIndex":2}]}` | `400` method not allowed
`200` `{ success: true }`
`500` `{ success: false, message: "error.message" }` |
+
+## Testing
+
+Linkin implemented tetsing using [jest](https://jestjs.io/).test cases live in [**test** dir](./__tests__/) . currently all the database manipulation functions are being tested in the pragmatic flow.