Skip to content

Latest commit

 

History

History
124 lines (74 loc) · 8.21 KB

CONTRIBUTING.md

File metadata and controls

124 lines (74 loc) · 8.21 KB
Raw

Contribute in the (front-end) development

The main objective of the project is to further develop and maintain the Assembly app.

The app is available through the major desktop and mobile browsers.

Architecture overview

Basics

The project's architecture identifies two modular blocks: front-end and back-end.

Languages

The front-end's source code is written with web languages; therefore, it's necessary to have basics in:

  • HTML: handles the structure of our pages.
  • CSS: holds the presentation (style) of our pages.
  • JavaScript: handles the business logic of our pages.

Quick example:

web languages

Through web development, we created a web app; specifically, a SPA (Single-Page Application).

To be precise, to handle the business logic of our app we don't use JavaScript directly, rather a "superset" of it, named TypeScript; in a few words, it's basically JavaScript with syntax for types. Therefore, if you know JavaScript, you won't have any problem; also: if you know PHP, you will find more similarities.

If you need it, online, you will find tons of free resources, tutorials and crash courses on these languages.

Frameworks

Of course, we didn't reinvent the wheel and wrote code from scratch; we instead took advantage of frameworks. Specifically:

  • Angular: a development platform built on TypeScript. If you have never used it before, I suggest watching reading the official documentation.
  • Ionic: a library of mobile-optimized UI components, gestures and tools. Using Ionic is very easy: you can explore the components library and mostly copy/paste the "blocks" that you need.

Here's an example of how the two frameworks affect the graphic result of our programming:

frameworks

Project structure

Here's the project folders/files structure:

initial project structure

Don't worry: you won't need to know or edit most of this stuff!

You will spend 90% of your time working on the front-end/src/app/tabs folder, where you will find two types of components:

  • Pages: are the pages accessible in the app by a particular link (e.g. /user).
  • Components: are the building blocks that compose a page (e.g. <app-user-card />).

Each component/page is represented by a set of files (not all of them are always present):

  • user.page.html: contains the HTML structure.
  • user.page.scss: contains the style/presentation code (CSS) .
  • user.page.ts: contains the business logic (Typescript).
  • user-routing.module.ts: contains the routing instructions (e.g. the page is reachable through the relative path /user).
  • user.module.ts: contains the imports of the related components and modules.
  • user.service.ts: contains the API requests and the logics to interact with the user's data model.

Developer tools and first steps

Make sure you

  • Have installed Git: for code versioning.
  • Have an account on GitHub: where our code repository and issues (User Stories) are.
  • Have installed Visual Studio Code: the IDE (Integrated Development Environment) that we use to write code. Not mandatory — you can use the tool you prefer — but suggested, since it has some extensions that will help in your job.
  • Have installed Node.js: we need to access the NPM (Node Package Manager) to install all the libraries and dependencies of our source code.
  • If you use Google Chrome, you can install the Angular Developer Tools extension to access some specific Angular debug features.

You may have most of this stuff already on your dev computer, but if you need help in installing or configuring any tools, let us know!

Next steps

  • Get confident with the main languages (HTML, CSS, TypeScript) and frameworks (Angular, Ionic) by reading some documentation and following any tutorial or course (you can find plenty of them for free online). If you have any questions, We're here to help! 😄
  • Explore the repository on GitHub to peek at the base source code and get to know the User Stories (Issues) that express the next features that we will implement.
  • Clone the repository locally to have the source code ready on your computer. Read more about cloning a repository from GitHub.
  • Start experimenting by running the local environment (localhost) and changing the code to your likings. See below for further instructions.

Starting the local environment

Make sure you have installed the project's latest libraries and dependencies (and compiled the models) by running in the terminal, from project's root:

cd back-end
npm install
cd ../front-end
npm install

Start the project locally by running (from the front-end folder):

npm run start

or from Visual Studio Code: Run > Start debugging or press F5 (Fn+F5 in some computers).

This will start a local development environment that can be accessed (once it finishes loading) with any browser (Google Chrome is suggested) at the address: http://localhost:8100.

Any change that you make to the code will be automatically reloaded in the browser (you should see changes almost instantly).

If you want to debug your code, you can open the Developer Tools of your browser.

⚠️⚠️ Since the app supports development and production stages, you need decide which to use when you run the front-end; in /front-end/src/environments/environment.idea.ts you can switch between "dev" and "prod" with the variable STAGE. Note: dev and prod environment have their own databases; this means that the app's contents will be different based on which environment you’re referring to with the variable STAGE.

Tackle an issue, develop and commit changes

When you're ready to try tackling a User Story, let us know! 💪

You will be assigned to the related Issue on GitHub, and you will start working on a new branch.

You will implement in your local code the changes that make the new feature work. It's always a good practice to carefully test the code that we implement!

When we are confident with the results, we can commit our changes and create a Pull Request to merge the changes in the main branch.

We will discuss together whether we can fix any problem or improve the code; finally, we will merge the changes and publish the new feature in the app.

Oh, here you can find some best practices about managing/committing/reviewing our code: it would be nice to follow them. 😉

P.S. here's another resource that presents everything you've read here.