-
Notifications
You must be signed in to change notification settings - Fork 6
For beginners
Welcome! We are very glad that you took an interest into our project and cannot wait to meet you!
This project is powered by a Django backend and a React frontend, linked by a REST API.
- If you have fully understood the previous sentence and already know about Django and React, please go to the project set up.
- If you don't really know what Django or a frontend is, please keep reading. The following sections will help you to know what you don't know and thus what you should learn or review before contributing to this project.
- A lot of things are listed here. Don't worry, we do not ask for a deep understanding of all of these notions — after all, the best way to learn is by doing.
- However, one must also know that some basic experience and knowledge in these fields is critical to get started.
In any case, if you have any question, even during your learning phase, do not hesitate to get in touch, we will be glad to help. ;)
We are building a website, so you should at least be able to broadly answer these questions:
- What is the difference between the Internet and the Web?
- What happens when you type https://www.google.com/ in your favorite browser?
- What is a server?
- How does a server… serve a website?
- What is HTTP / HTTPS? What is the difference between these two?
Also learn about the HTTP verbs and the HTTP status codes (the semi-dozen which are the most often used).
You should first know about the important distinction between backend and frontend. In a nutshell (read this for a deeper explanation):
- The backend manages the interaction with the database (that is the website data). It runs exclusively on the server.
- The frontend manages what the user sees in their Internet browser.
Sometimes, the backend and the frontend are powered by the same framework. However, the most usual configuration is to have them written in two different frameworks, and make them communicate with each other by an API, created by the backend and used by the frontend.
For instance, the Portail des élèves relies on a Django backend (and more specifically the Django REST framework) and a React frontend (with the Tabler CSS framework).
As a result, as the backend and the frontend are powered by different programming languages (Python for the backend, TypeScript, HTML and CSS for the frontend), they can actually be developed by completely different teams, the API linking the two parts together. This means that you can choose which one you prefer and stick to it… or become a full-stack developer!
Here is a list of the tools that we use (and that you have to use too) or warmly recommend:
- Git, because we are on GitHub. Here is an introduction, here an explanation of Git terms, and this is a recap of the important commands. And mind the distinction with GitHub!
- If you don't know which software to use to write code, we recommend either PyCharm (the Community version is free, the Professional version is free for students), or the free Visual Studio Code. These are actually IDEs (Integrated Development Environment), which means there are not only text editors, but also come with tons of features to make your like easier.
- You will find tools specific to the backend or the frontend in the dedicated sections.
We will now explain what the backend and the frontend are in a little more details.
Our backend uses Python. If you are interested into the backend, you thus have to know the basics of Python as well as having a good understanding of the oriented-object programming. Knowing some advanced concepts such as the decorators will help you, but are not necessary in a first place (you can learn them when you need them). There are plenty of tutorials available on the Internet, here is one if you feel lazy. Please make sure that you learn Python 3.
Django is a web framework written in Python. It can be used on its own as a full-stack solution (frontend and backend), but we only use it as a backend. In this project, Django will thus manage the database and create the REST API (we will talk about REST and the Django REST framework a bit later).
Then, you should follow the Django framework, which will be enough for our purposes.
Our database is powered by Postgres SQL. This is more as a side-note, as you should never directly use SQL; you will typically only use Postgres during the installation.
Remember that the backend and the frontend communicate with each other through an API.
For this project, we will be using a REST API, which is a special way of building an API. Explaining REST in a paragraph is neither easy nor efficient, so you should definitely read a tutorial (this one, for example). Make sure that you have correctly understood HTTP before, you will need to know about the HTTP verbs (GET, PUT, POST…).
We use the Django REST framework (often abbreviated DRF) to build our REST API. Go through the DRF tutorial (not the quick start, the full tutorial, especially if you are a beginner). Learn at least about the serializers, the viewsets and the permissions.
- Learn how to use pip and what
pip install -r requirements.txt
does. - Learn how to set up and use a virtual environment (we recommend venv, which is the official way of doing it). Here is a tutorial for both pip and venv. Also learn how to tell you IDE to use a virtual environment.
- In order to keep the code well formatted, use Black. You can configure any IDE to run it automatically on save.
- We unit test a lot, with the integrated Django and Django REST framework unit testing modules. If you are interested (and you should!), start by reading a Python tutorial on the subject then go on to the Django documentation and the Django REST framework documentation.
- If you are stuck, a good starting point is Googling your error or looking on the documentation of the language or the framework that you are using (Python, Django, Django REST Framework). Bookmark them.
- Of course, we are always happy to help, but please search a bit on your own before.
You should know about the basic bricks of the Internet: HTML and CSS. Here is a tutorial to get you started if you have never tried any of these.
Note that we won't be using very advanced HTML in this project, but you should at least be familiar with the basics (headings, images, lists, tables…) to get started.
We will use a CSS framework, Tabler, based on Bootstrap, the most popular CSS framework (look at the Wikipedia article if you don't know what a framework is). In practice, you don't have to be a master of Bootstrap to get started; however, it's better to know some basic CSS (selectors, the most common properties…)
Our frontend uses TypeScript, which is JavaScript with (nice) additions.
We first recommend to learn JavaScript on its own: here is a tutorial; focus on the “advanced” parts about the asynchrony or the DOM events. Then, you can have a look to TypeScript; don't worry, it will be quite easy if you know JavaScript.
React is a framework written in JavaScript which can be used with TypeScript. As a reminder, it will use the REST API created by the backend to interact with the user (that is it will render and treat the web page).
The React website has a very good tutorial which is completed fairly quickly. You should then read the main concepts. And, finally, read about the hooks, which the new version of React that we use here.
A router allows us to have nice URLs for our Web application; basically, it links a specific URL to a specific React component. We use React Router, which is very easy.
As said earlier, we use Bootstrap, which comes in a React version. No extra learning is required for using it, it is just a matter of replacing some of your HTML tags by the provided ones.
We use axios to make HTTP requests and React Query to cache them.
Formik helps us to manage our forms.
This is a living document, YOU should feel responsible for updating it.
- Code workflow
- Tests
- Project management (issues, PR, reviews)