From 096fff82ac04428be614d28c0c21a792ad612bc7 Mon Sep 17 00:00:00 2001 From: Varun Sethu Date: Sat, 25 Feb 2023 12:28:34 +1100 Subject: [PATCH] updating documentation --- README.md | 32 ++++++-------------------------- backend/README.md | 27 ++++++++++++++++++++++++--- 2 files changed, 30 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index b7f134c2..bc9c1c76 100644 --- a/README.md +++ b/README.md @@ -22,37 +22,17 @@ run: ## Environment Variables -Please note that you have to add /Config/.env.dev and include the env secrets. Please contact `laurlala#1696`, `jumbo#9999` or `Mae#6758 -` on discord for these if you don't have them :) +Please note that you have to add /Config/.env.dev and include the env secrets. Please contact `laurlala#1696`, `jumbo#9999` or `Mae#6758` on discord for these if you don't have them :) ## Postgres Instructions -access interactive terminal by running `docker exec -it pg_container bash` +Access interactive terminal by running `docker exec -it pg_container bash` now run this command `psql -d test_db -f infile` to load the dummy data we have prepared in ./postgres/infile or run `make pg` - -## Some Resources -Our editor uses quite a few algorithms so below is a list of resources you can use to learn about them and hopefully contribute to the editor :) - - [Differential Synchronisation Algorithm](https://neil.fraser.name/writing/sync/eng047-fraser.pdf) - - [Myer's Difference Algorithm](http://www.xmailserver.org/diff2.pdf) - - [A cool blog post](https://blog.jcoglan.com/2017/02/12/the-myers-diff-algorithm-part-1/) - - [String Difference Strategies](https://neil.fraser.name/writing/diff/) - - - ## FAQs: -- Q: something is broken what to do? -- A: run `make clean` then run `make dev-build` again, should fix it - -- Q: something is horibbly broken -- A: manually remove all images in docker desktop GUI app and re-run `make dev-build` again - -- Q: it says I don't have docker installed, but I have already installed docker before -- A: open your docker desktop app then re-run it - -- Q: it still doesnt work -- A: google docker desktop WSL2 not detecting docker +- Q: Something is broken what to do? +- A: Run `make clean` then run `make dev-build` again, should fix it, if it is still broken then manually remove all images in the docker desktop GUI and re-run `make dev-build`. -- Q: Docker is taking up alot of space how to remove? -- A: docker is a ram/storage drainer but, you can remove useless volumes, run `docker volume prune` +- Q: Something has gone wrong with Docker, where can I find docker resources? +- A: Docker is rather well documented, check out the docker website: https://www.docker.com/ to try and resolve your issue. diff --git a/backend/README.md b/backend/README.md index 5b2224bb..24089dba 100644 --- a/backend/README.md +++ b/backend/README.md @@ -8,12 +8,33 @@ The backend folder contains all our backend code 🤯. Theres a few important fo - ### `endpoints/` - Contains all our HTTP handlers + methods for decorating those handlers, additionally provides methods for attaching handlers to a `http.ServeMux` - ### `editor/` - - Contains all the backend code for synchronisation (bit of a mess right now 😭). It is essentially just a big implementation for the differential sync algorithm and supports extension via the construction of `extensions` + - There are currently 3 different editor backends, once the OT backend is fully complete this will collapse down to just OT + - The OT folder contains our implementation of the operational transform algorithm, specifically Google WAVE OT + - The pessimistic editor is a lock based editor, instead of implementing an optimistic concurrency protocol it simply locks the editor while a conflicting client is using it + - The diffsync folder contains all the backend code for synchronisation (bit of a mess right now 😭). It is essentially just a big implementation for the differential sync algorithm and supports extension via the construction of `extensions` - The package allows multiple clients to be connected to the same document and ensures that each client sees the exact same document state (via a best effort diff + patch) - Currently only works on strings with no inheret structure but in the future will work on JSON documents too 😀 - - ### `algorithms/` - - Mostly algorithms used by the editor such as Myer's string difference algorithm (glorified BFS tbh) and some prefix/suffix computation - ### `environment/` & `internal/` - Methods/packages that can be used to retrieve information about the current environment and other internal utilities - ### `client` - WIP TypeScript implementation of client server for operational transform + + +## Papers worth Reading +Most of the complexity of the CMS backend is within the editor, to aid with your tickets we have accumilated a few great resources that are worth a read. + - [A survey of OT algorithms](https://www.researchgate.net/profile/Ajay-Khunteta-2/publication/45183356_A_Survey_on_Operational_Transformation_Algorithms_Challenges_Issues_and_Achievements/links/5b9b27dca6fdccd3cb533171/A-Survey-on-Operational-Transformation-Algorithms-Challenges-Issues-and-Achievements.pdf?origin=publication_detail) + - [The Jupiter Operational Transform Algorithm](https://lively-kernel.org/repository/webwerkstatt/projects/Collaboration/paper/Jupiter.pdf) + - [Google Wave OT (Multi-client single server OT)](https://svn.apache.org/repos/asf/incubator/wave/whitepapers/operational-transform/operational-transform.html) + - [Transformation algorithms for ordered n-ary trees](https://arxiv.org/pdf/1512.05949.pdf) + - [Differental Synchronisation](https://neil.fraser.name/writing/sync/eng047-fraser.pdf) + +## Language Documentation & Resources +If this is your first time using Go then the following resources might be of some use: + - [2022 CSESoc Dev Go Workshop](https://drive.google.com/file/d/1zLJHkcktLFXKXs6MFNVmWyfVtTHq8ng8/view) + - [Unit testing in Go](https://www.digitalocean.com/community/tutorials/how-to-write-unit-tests-in-go-using-go-test-and-the-testing-package) + - [Interface mocking & gomock](https://itnext.io/how-to-write-better-unit-tests-in-go-using-mocks-4dd05e867b17) + - [Generic Programming in Go](https://go.dev/doc/tutorial/generics) + - [Concurrent Programming in Go](https://golangdocs.com/concurrency-in-golang) + - [Communicating Sequential Proceseses (Go's model of concurrency)](https://www.cs.cmu.edu/~crary/819-f09/Hoare78.pdf) + - It's not required but its a nice read + - [Godoc](https://go.dev/blog/godoc) \ No newline at end of file