Laelith Wiki

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

====== Being a Mage in Laelith – A Modest Guide ======

All persons participating in the technical development of Laelith (Front-end and Back-end Developers, DevOps Engineers, Database Administrators, UI Designers, Crypto Engineers, Cartographers, 2D and 3D Designers, etc.) are collectively called “Mages”. This is because “Any sufficiently advanced technology is indistinguishable from magic” (Arthur C. Clarke).
 
So, if you are one of them, welcome and a big thank-you! Without you, Laelith cannot live in the Metaverse.
 
Here is a modest guide that will help you get acquainted with a few philosophical and technical principles that will make your technical journey in Laelith more enjoyable for you and your co-Mages.

===== Principle #1: “It’s better when it’s simple!” =====

This is highly subjective, of course: depending on their own skills and expertise, each of us will have different opinions about what is simple and what is complicated.
 
We all need to keep in mind that some fellow Mages will have less experience or knowledge than others. Still, we want everyone to be able to contribute, so let’s keep things simple.
 
  * Be wary of this cool bleeding-edge tech you want to have fun with.
  * Avoid exotic programming languages, obscure tools, complicated architectures, “tricks” and “hacks” – even if they are intellectually elegant.
  * Document what you do, especially how to install it in a development context and in a production context. You will know you are successful in this if another user gets the “instant gratification effect” when installing and trying your code for the first time.

===== Principle #2: “Code to minimum, put it in the hands of users quickly, and be ready to throw away and rewrite everything” =====

{{ en:laelith:high-terrace:mages-peaks:mages-principles:matt-palmer-ipum7ket2jo-unsplash.jpg?nolink&400|}}

In opposition to the [[https://en.wikipedia.org/wiki/Principle_of_least_effort|Principle of Least Effort]], over-engineering is a common disease in software development. It can come from several factors: poor or incomplete specifications from stakeholders, personal desire to impress others or to indulge oneself, the will to do the Big Thing the right way from the get-go, etc.
 
This is a trap. Because the Laelith project is a highly experimental one, we favor an ultra-short iterative approach to collect feed-back and adjust as quickly as possible. Ideally, an iteration should take only one or two days: you code one single feature, test it and you push it to production. Avoid releasing multiple features at the same time, especially if they are unrelated. We absolutely need to stay away from the “Big Bang” release syndrome.
 
This also means that you should be prepared to change or even throw away large parts of your code. This is fine because you won’t be dealing with lots of code anyway (one or two days of work at most), so you won’t feel too bad about it.
This also allows quick and easy rollbacks if you happen to break anything (don’t tell us it never happened to you).
 
Example: the data of the first version of the Laelith map were stored in a simple static JSON file directly loaded by the Map JS code. This was very basic, but it allowed us to define a first data model, get something running, and adjust the data structure and values super quickly. Later, came the need to build an API, so the map was changed to get data from a REST endpoint. However, this endpoint was merely piping the same static JSON file, which had just been moved to the API project. After a while, the Laelith Wiki came into play: the JSON file was reduced to its bare bones, and all the texts and images were moved to the Wiki. The API endpoint would collect and merge the remaining static data from the JSON file and the dynamic data from the Wiki. Finally, because we needed more flexibility, the static JSON file was abandoned and replaced by an SQL table.
One could argue that it was obvious that we would have to end up with a database, and that we would have saved time doing this from the start. We strongly disagree. Had we done so, we would not have introduced the Wiki integration as early in the project. Changing the data model would have been more cumbersome than just editing a plain JSON text file. And it also allowed us to postpone infrastructure needs until we had no ways around using a database because of the emerging needs.\\
//Jan 2023 Update: now that we have 20,000+ Cadastre elements, we combine a monolithic JSON file for the geometry with data coming from the Wiki and from the database to build a huge hierarchy of 20k+ cached small JSON files.//

===== Principle #3A: “Don’t reinvent the wheel” =====

Use standard, well maintained, and popular libraries. The number of libraries out there is so vast that there is surely someone who already resolved the problem you are trying to tackle. So, make sure you investigate these npm, Composer, Gems, etc. package managers before starting your own code. Just be careful about the license: MIT or similar are preferred. Avoid GPL or L-GPL because of their contamination side-effects.

===== Principle #3B: “…but it may still be useful to craft your own scooter” =====

{{ en:laelith:high-terrace:mages-peaks:mages-principles:dmitry-vechorko-43npci0njly-unsplash.jpg?nolink&400|}}
At the same time, ask yourself if you are not crushing a molehill with a bulldozer where a simple shovel would have made the job just nicely (Principle #1). Some libraries are so bloated, trying to solve everything by writing the Equation of the Universe, that they become huge. As a result, you overload your code. On top of this, the number of dependencies is so large that such libraries can become fragile or introduce incompatibilities. This can become a big problem.

So, sit back and ask yourself: “do I really need to include this wonderful but huge library to just implement this simple feature?” Maybe a better solution would be to get inspiration from it (read the code, Luke), and (re)write this one dozen lines of code you needed?

This is especially true for the front-end projects, where large librairies mean a slower UI, which is an absolute repeller. Only use what is needed here and communicate with the other Mages before adding a new significant dependency.

===== Principle #4: “Communicate in the #mages-peaks Discord channel” =====

We Mages communicate primary in the #mages-peaks Discord channel. Write about what you are currently coding, announce when you push a Pull Request that you want others to review, ask questions, call for help, tell jokes, etc. In a software development project, you simply cannot over communicate.
 
Please always remain friendly and helpful to your fellow Mages (some are beginners eager to learn). Patience and respect will always earn you great rewards. Avoid meaningless “platform wars” or other similar silly debates – unless it’s to make a joke out of it (“tabs or spaces?”). And as usual in these kinds of channels, no political, religious, philosophical, moral, or cultural debates, please. There are other forums and places on the Internet for these topics.
 When we release a new feature, it’s always a great idea to announce it in the #laelith-gazette channel. We have a short format called “A Scroll from the Mages” that works well.
 
You are also welcomed to check out the #help channel and help the poor Pilgrims who are lost.

{{ en:laelith:high-terrace:mages-peaks:mages-principles:sharon-mccutcheon-uxs73pngytc-unsplash.jpg?nolink&300|}}
===== Principle #5: “GitHub and Pull Requests are our oyster” =====

One general idea about the Laelith architecture is to build small services that communicate together. Each service will have its own GitHub repository.
 
When pushing some new code, please follow the [[https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests|Pull Request pattern]]. This is a great way to inform your fellow Mages about what you are doing, and it really helps catching bugs before rolling out to Production. It also has another positive side-effect: by knowing that other people will read and comment on your work, you will naturally write more readable and better organized code.
 
When reviewing and commenting someone else’s Pull Request, we find that [[https://gist.github.com/mrsasha/8d511770ad9b282f3a5d0f5c8acdd10e| these recommendations GitHub]] are good guidelines to get started. Make sure you read and think about them.

===== Principle #6: “We believe in Unit, Integration and Acceptance Testing, but this is not a religion” =====

If your development framework supports it, we highly recommend that you code unit and integration tests as you develop your features. This will make code refactoring easier. It will also make code sharing easier, especially with beginners, because automated tests allow newcomers to ensure that they did not break anything when they change your code.

End-to-end testing (aka Acceptance Testing) is great too. For example, the API and the Identity Servers both use Gherkin-based Acceptance Tests that are very useful.

This being said, there are some areas when it is more difficult or makes less sense to perform automated testing – or it becomes too much of a chore to maintain. An example is to perform automated tests on user interfaces. This is difficult. If you want to walk this path, check out advanced tools such as [[https://playwright.dev/|Playwright]] or similar. And always keep in mind Principle #1.

{{ en:laelith:high-terrace:mages-peaks:mages-principles:dmitry-vechorko-q7qznp-vslm-unsplash.jpg?nolink&300|}}
===== Principle #7: “Google Doc then Wiki” =====

“Specs are always wrong” supposedly said Elon Musk, but this is no reason for not writing some! Putting your ideas on paper to explain them to others forces you to clarify them (see the [[https://en.wikipedia.org/wiki/Rubber_duck_debugging|Rubber duck debugging]] effect).
 
Ideas are very volatile and fast evolving, especially during their infancy. This is why it is important at the beginning to make them easy to write and be commented, especially in the Laelith project which is a very collaborative one. We just don’t drop a 10-page document on the head of other developers telling them “OK guys, here is how we’re going to do it, make sure you comply!”.
 
We found that the following process works well:
  * We start by writing a Google Doc. This makes the document very easy to write and be commented on by everyone. Multiple developers can edit the document, we consider that the initial writer does not “own it”.
  * After some time, and after some code was written, it is likely that the document will stabilize. Either because it has become outdated (in which case, we just archive it and move on), either because a consensus has been reached and the developed code was successful. In this later case, we copy the document content to the Laelith Wiki in [[en:outskirts:mages-peaks|the Mages Peaks section]], which makes it a public official technical memo from the Mages.

===== Principle #8: “We don’t build Norman Doors” =====

The User Interface matters most of all. This is the occasion of hot debates about colors and layouts and styles. There are also people who confuse UX (User Experience) and UI (User Interface). Just keep this in mind: if what you develop is not usable, people won’t use it. Many engineers overlook this trivial idea, often because they were not trained in this important aspect of their work. The result is the zillions of devices and systems that we struggle with in our everyday lives. In the Industrial Design space, this now has a name: “Norman Doors”. You know, these doors that you never know if they should be pushed or pulled. Make sure you watch this fun video to learn more: https://www.youtube.com/watch?v=yY96hTb8WgI

[[https://en.wikipedia.org/wiki/Don_Norman|Don Norman]] is the inventor of Human-Centric Design (observe, design, prototype, and test), and his “Design of everyday things” book should be compulsory in every engineering course.

So as software engineers, we must pay the utmost attention to the quality and usability of the user interface (how things look like) and of the user experience (how people use them).

Another key point of the UI is that it must remain responsive – a sluggish UI is the fastest way to “lose” users. The base Map, especially, must always remain fast to manipulate. For example, only load DOM elements for other features when they are needed and unload them after.

===== Principle #9: “We pay attention to details” =====

This principle is a result of the previous one: the success or failure of UI and UX always lies in tiny details. But this is also true for code architecture, code writing styling, naming things properly, designing data models, writing relevant comments, performing good peer reviews, etc. Details are important, and yes, it can be tedious to polish these last 10% (which often take you much more than 10% of the project time).

{{ en:laelith:high-terrace:mages-peaks:mages-principles:sander-sammy-phoypwql--w-unsplash.jpg?nolink&300|}}
===== Principle #10: “We pay attention to security” =====

The crypto world is littered with horror stories of attacks, scams, thefts of virtual currencies, etc. But it is not unique to the crypto world: the history of the Internet is full of similar stories (a great and fun book from the 80’s is [[https://en.wikipedia.org/wiki/The_Cuckoo's_Egg_(book)|The Cuckoo's Egg]] from Cliff Stoll). SQL injections, privilege escalations, brute force attacks, bugs and OS vulnerabilities exploits, etc. the list goes on and on. When money or power are at stake, people become especially motivated and creative to attack a system. And there is always the “social engineering” that no technical system will prevent.

So, we always must keep this in the back of our minds when we code. Good practices should be applied at the very moment you are coding, not as something that you do later – because you will forget. Sanitize your input values, use an SQL library that provides tools against injections, code defensively, don’t expose or communicate details about the production environment, etc.

And never give away your private keys – of course.

===== Principle #11: “English only, please” =====

The Laelith in the Metaverse project is a very international project with people from all over the world. It was originally developed in France during 30+ years by a very large team of French authors. We have the ambition to make it a worldwide success, which is why the main idea is “English first”. We understand that it may not be easy for non-native speakers, but we will repel newcomers if they have the (wrong) feeling that it’s a French project when they discover Laelith. So write in English – even if it’s “broken English”.

===== Principle #12: “We have a duty to the Laelith Community” =====

Last but not least: we Mages have a very specific set of superpowers. Our duty and or reward is to use these to serve the Laelith community. This should be the North Star of everything that we do: does this new feature, technology, idea, trick, effort, etc. bring something useful and valuable to the Laelith community? Everything else, including our ego, is irrelevant.

{{ en:laelith:high-terrace:mages-peaks:mages-principles:amandine-bataille-31muw23ql74-unsplash.jpg?nolink&600 |}}

== Photos Credits ==
  * Photo by [[https://unsplash.com/@mattpalmer?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText|Matt Palmer]] on [[https://unsplash.com/s/photos/wizard?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText|Unsplash]]
  * Photo by [[https://unsplash.com/@vechorko?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText|Dmitry Vechorko]] on [[https://unsplash.com/s/photos/wizard?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText|Unsplash]]
  * Photo by [[https://unsplash.com/@sharonmccutcheon?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText|Sharon McCutcheon]] on [[https://unsplash.com/s/photos/wizard?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText|Unsplash]]
  * Photo by [[https://unsplash.com/@sammywilliams?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText|Sander Sammy]] on [[https://unsplash.com/s/photos/wizard?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText|Unsplash]]
  * Photo by [[https://unsplash.com/@amandine_bataille_photo?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText|Amandine BATAILLE]] on [[https://unsplash.com/s/photos/wizard?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText|Unsplash]]

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Share Alike 4.0 International