Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +Tech Start's Django Guide |
Django is a free and open source python framework that lets you build awesome backends for websites, apps, and more. You can use it to host databases and build secure APIs for them without writing a line of SQL. You can also use it to create multi-page applications with dynamically served content. It makes it easy to get started building complex functionalities by automating a lot of the boilerplate code that you'd normally have to write.
We recommend that you have a basic knowledge of python before using django! This will help you debug any errors that you get.
(Img src: https://medium.com/crowdbotics/when-to-use-django-and-when-not-to-9f62f55f693b)
Setup
Before you get started with Django, you should set up your environment. You should have a recent version of Python installed. You can follow the directions here:
https://docs.djangoproject.com/en/3.1/howto/windows/
You should make a venv for your django project.
Video tutorial for venv windows: https://www.youtube.com/watch?v=APOPm01BVrk
Video tutorial for venv mac/linux: https://www.youtube.com/watch?v=Kg1Yvry_Ydk
Note: if you're using Git Bash on windows, use $ source venv/scripts/activate
When you're done using your virtual environment, just enter $ deactivate
https://docs.djangoproject.com/en/3.1/intro/tutorial01/
$ python -m pip install Django
Get Django installed once you have created your virtual environment.
$ python -m django --version
// Checks if you have django installed
Next, cd into the folder which you want to contain your project and run the following command:
$ django-admin startproject pNameHere
// starts project. cd into pNameHere folder.
Good to know: Projects vs. apps What’s the difference between a django project and a django app? An app is a Web application that does something – e.g., a Weblog system, a database of public records or a small poll app. A project is a collection of configuration and apps for a particular website. A project can contain multiple apps. An app can be in multiple projects. |
$ python manage.py startapp yourAppName
This creates an app within your project. You'll need to be in the same folder that holds your project's manage.py
Next step: include your app in the INSTALLED_APPS fields in settings.py (just the name)
INSTALLED_APPS = [
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
#Add your app name like this!
'myAppName',
]
Writing Models
Models allow you to define the content of your database. If you don't need content in your database, you won't need models.
You can follow along with this section here:
https://docs.djangoproject.com/en/3.1/intro/tutorial02/
More about models: https://docs.djangoproject.com/en/3.1/topics/db/models/
You will define all your models in models.py, located within the folder for your app.
from django.db import models
# Create your models here.
class Album(models.Model):
name = models.CharField(max_length=200)
artist = models.CharField(max_length=100)
year_released = models.DateField()
def __str__(self):
return str(self.name)
class Song(models.Model):
song_name = models.CharField(max_length=100)
album = models.ForeignKey(Album, on_delete=models.CASCADE)
num_streams = models.IntegerField()
def __str__(self):
return str(self.song_name)
Each model should correspond to the structure of a table of a relational model of a database. If you don't know what this means, ask someone who has taken CPSC 471 (or an equivalent databases course)
Django can convert these into real SQL tables!
- Good to know: Primary Keys: In the above example we didn't specify any ids for our models (normally, with databases, you want an id to be your primary key). Django automatically creates an ID field to be the primary key for each model and takes care of auto-incrementing, unless you specifically override it. I don't recommend overriding, it's not worth the effort (and its doubly complicated and not worth it to have a primary key composed of several fields)
- Good to know: __str__: the __str__ function is Python's default function for string representation. In this case, it's good practice to override this for your models. This will help you understand your data if you login via the admin view (I'll show how to do this later)
- Good to know: Foreign Keys: See the Song model class for how you can reference a foreign key belonging to another model (in this case it refers to Album). You don't need to refer to a foreign model's keys directly, all you need to do is specify which table you are referencing. Also note: if you are referring to a table, it needs to be defined above the point in the code where you are referring to it.
There are more options that can be explored about how you can define your models, but this should be a good base for you to do your own research :)
Now we're ready to convert these into a real database! By default, Django will make a sqlite file that has your database.
Converting models into your database https://docs.djangoproject.com/en/3.1/intro/tutorial02/ >> python manage.py makemigrations appName Creates migrations for the changes you made in appName >> python manage.py migrate Migrates the changes you made into your database |
Run your app
Whenever you are ready to run your server, just call this command!
>> python manage.py runserver
By default, this will run the Django server on localhost:8000. View the django documentation to see how you can run it on a different port. You can now access it from your web browser by visiting http://localhost:8000 !
You can also create a superuser (admin) to view the inner contents of your database. To do this, you first need to create them from the command line using the following command:
>> python manage.py createsuperuser --username yourNameHere --email yours@email.ca
This will create a super user with your provided info (it will prompt you to enter a password as well).
The following command creates a token for the superuser that you can use for authentication in requests. If you are not using Django Rest Framework, this is not applicable to you.
>> python manage.py drf_create_token yourSuperUserName
Note: if you're trying to run these for your deployed app on heroku, you need to prepend heroku run before those commands! See the Heroku section for a description on how you can deploy it.
You can see the admin page of your website to view the inner content of your database. This is automatically created by Django. Visit http://localhost:8000/admin and enter your passcode.
If you want your models to show up in the admin page, you will need to specify them in admin.py like this:
from django.contrib import admin
from .models import Album, Song
# Register your models here.
admin.site.register(Album)
admin.site.register(Song)
Once you log in to the admin site, you should see something like this. From here, you can add & remove database entries.
URLs
URLs allow you to define the paths that exist in your system, and what happens when you call them.
URLs documentation: https://docs.djangoproject.com/en/3.1/ref/urls/
How URLs are processed in Django: https://docs.djangoproject.com/en/3.1/topics/http/urls/#how-django-processes-a-request
Read more: https://docs.djangoproject.com/en/3.1/intro/tutorial03/
If you're constructing a big application, it's standard practice in django to include different apps for each part of your system, and link them to the main project.
However, since we're only making small-scale side-projects, it's fine to ignore this best-practice and include everything in a single app. Just understand that in a large industrial scale project you wouldn't necessarily want to do this.
// urls.py in a project:
from django.contrib import admin
from django.urls import path, include
urlpatterns = [
path('admin/', admin.site.urls),
path('myApp/', include('myApp.urls'))
]
// example urls.py in myApp folder:
from django.urls import path
from . import views
urlpatterns = [
path('hello_world', views.ping, name='Hello World!'),
path('hello-x/<str:hello_to>', views.hellox, name='Hello to x'),
path('hello-x/<print_me>/print', views.printx, name='Print this!'),
path('goodbye', views.goodbye, name='goodbye'),
]
Now you can visit a path using http://localhost:8000/myApp/hello-world, for example.
Views
Views allow you to define what happens when you access a certain url in your system (using your browser, an API tool like Postman, or something else altogether). In your views, you could define interactions with the model (your database) or entirely different interactions altogether. You can use the definition of the view to call external processes.
If you want to make more complicated views and understand the Request and Response items, read this:
https://docs.djangoproject.com/en/3.1/ref/request-response/
To understand views more in-depth, read the documentation: https://docs.djangoproject.com/en/3.1/topics/http/views/
Here are some simple examples of what you can do with a view. Note that these are just examples and don't represent best practice at all.
from django.http import HttpResponse, response
# views.py
def ping(request):
myRes = "Hello World!"
return HttpResponse(myRes)
def hellox(request, hello_to):
myRes = {"My Reply": "Hello " + hello_to}
return response.JsonResponse(myRes)
def printx(request, print_me):
print("Hello to " + print_me)
return response.HttpResponseNotFound("I printed it!")
def goodbye(request):
if not (request.method == 'GET'):
return response.HttpResponseBadRequest()
queryParams = request.GET
msg = queryParams.get('msg', "Gamers")
return response.JsonResponse({"Reply": "Goodbye " + msg})
Now, we want to adhere to DRY (Don't repeat yourself) when creating views. Therefore, it is almost always best to define your views as Class-Based views (CBVs) which handle more of the boiler plate code for you and help ensure your views follow standards.
Please read more about class-based views here: https://docs.djangoproject.com/en/3.1/topics/class-based-views/
Both the above docs and the docs for views also show how you can interact with your database items through a view. But, if you're building an API, I highly recommend using the tools in the following section: Django REST Framework.
Once you have defined your views and given them a corresponding url, you can test them out.
>> python manage.py runserver
Run your server, and using either a web browser, or preferably an API testing tool like Postman (https://www.postman.com/) access the proper urls (ex. http://localhost:8000/myApp/hello_world) to see if they have the expected behavior.
Django REST Framework
Django REST Framework is an add-on to Django that makes it simple to develop REST-compliant APIs. There is great documentation here: https://www.django-rest-framework.org/ <--- FOLLOW INSTALL INSTRUCTIONS
What is a RESTful framework? Learn more here: https://restfulapi.net/
Django REST Framework provides you with tools to make class-based views to easily implement database CRUD (Create Read Update Destroy) operations, as well as define more complex operations.
Before we define any endpoints with Django REST Framework, let's make some serializers.
Serializers
Django REST Framework uses serializers as a way to perform translation of your models from your python code and your database into data formats like JSON and XML that an API might use. Read more about them here:
https://www.django-rest-framework.org/api-guide/serializers/
We should define some basic serializers so that we can make API endpoints that interact with the content of our database models.
- Create a new file called serializers.py inside the app you want to use serializers with.
- Create your serializers. Give them a relevant name (though the exact syntax is not important)
- List the fields that you want your serializer to translate. If you don't want it to translate a particular field, then don't include it.
Here's an example, using the Song and Album models we defined earlier. Here's what's at the top of serializers.py:
from rest_framework import serializers
from .models import *
class SongSerializer(serializers.ModelSerializer):
class Meta:
model = Song
fields = ("id", "song_name", "num_streams")
class AlbumSerializer(serializers.ModelSerializer):
class Meta:
model = Album
fields = ("name", "year_released", "artist", "id")
Make sure your fields match exactly the names that you used in your models.
You may be curious why I also included an id, when we didn't define one in our models- this is because Django auto generated an id for us in this models because we didn't specify a primary key. This id field always has the name id. It is often useful for our API, so we'll include it.
We can also create multiple serializers for the same models, if we wanted different behavior. For example, what if we wanted to include the album id of the song?
class SongSerializerWithAlbumId(serializers.ModelSerializer):
class Meta:
model = Song
fields = ("id", "song_name", "num_streams", "album")
This would include the album's PK (in this case, it's id, but if the PK was different, it'd be something else).
What if we wanted to include the full album info when an api request was made to see the song? Here's another example serializer that we could make:
class SongSerializerFullAlbum(serializers.ModelSerializer):
myFullAlbumDesc = AlbumSerializer("album", read_only=True)
class Meta:
model = Song
fields = ("id", "song_name", "num_streams", "myFullAlbumDesc")
It's using our album serializer from earlier to serialize a field, which must (read only is an optional parameter that makes it so that it's only included in reading requests, not create/update/destroy.)
This was just an introduction to serializers. If you want to use more complex behaviors, you'll have to do the research on your own.
Django REST Framework: Class based Views
Pre-requisite to this section: understand URLS and views in vanilla Django, and read the serializers section |
More reading: https://www.django-rest-framework.org/tutorial/3-class-based-views/
Video overview of similar topic: https://www.youtube.com/watch?v=akvFA5VMXJU
You can use Django's Class Based Views to quickly create views that can do CRUD (Create, Read, Update, Destroy) operations on your database.
In views.py:
from rest_framework.views import APIView
from rest_framework import generics
from rest_framework import status
from .models import *
from .serializers import *
Some class based views that we'll define. Right now these are just the generic create, read, update, destroy views. By defining these views with the classes, Django REST Framework takes care of the default behavior for us. It's that easy!
class SaveSong(generics.CreateAPIView):
queryset = Song.objects.all()
serializer_class = SongSerializerWithAlbumId
class GetSongs(generics.ListAPIView):
queryset = Song.objects.all()
serializer_class = SongSerializer
class DeleteSong(generics.DestroyAPIView):
queryset = Song.objects.all()
serializer_class = SongSerializer
class UpdateSong(generics.RetrieveUpdateAPIView):
queryset = Song.objects.all()
serializer_class = SongSerializerWithAlbumId
Notice that we need to make the create and update serializers include the album ID- if we didn't then you couldn't create song objects since their album id must be not null.This same principal applies to any model that has a foreign key which isn't allowed to be null.
Before we can use the views we created, we need to hook them up to a URL, just like you would for any other view. Do keep in mind that we need to call the as-view function on them, though. Here is an example of the URLs for the previous views. This pattern is how we normally define CRUD endpoint urls for any entity in a database
path('song', views.GetSongs.as_view(), name='songs'),
# Create a song
path('song/create', views.SaveSong.as_view(), name='Save Song'),
#Updates a specified license with information
path('song/<int:pk>', views.UpdateSong.as_view(), name='Update Song'),
# Deletes a song specified by pk
path('song/<int:pk>/delete', views.DeleteSong.as_view(), name='Delete Song'),
If you are using a pk that is not an int (you manually defined a pk instead of using the default id generated), you'll have to specify that accordingly.
What if we want more complex behavior beyond the default predefined classes? We can modify them to add more conditions to what is returned.
In this example, we added an optional way to filter songs by album, using a query_param called album. You'll need to read documentation and tutorials if you want to know more about the custom behavior you can define within your Django REST Framework views.
class GetSongInAlbum(generics.ListAPIView):
serializer_class = SongSerializer
def get_queryset(self):
queryset = Song.objects.all()
alb = self.request.query_params.get('album', None)
queryset = queryset.filter(album=alb)
return queryset
If you have a view that isn't necessarily linked to CRUD actions, or has more complex usage and needs more custom defined behavior, you can use APIView.
Test out your Django REST API
Compile and run your app with
$ python manage.py runserver
Use your bugfixing wizardry to fix any errors that might show up. Now you should be ready to give those predefined endpoints you made for a spin!
Here's some examples that I did using Postman for API testing. If you used Django REST Framework, it should also come with a built-in API testing tool that you can use in your browser.
Here's a simple GET request. This is a database read operation, and it's pretty simple. Your browser is making GET requests to every URL you visit while you surf the web.
Request | |
Response |
Here's a POST request (it's post because we're creating or Posting new data) to our create route. We should include the key-value pairs for the song we want to create in the Body of our request.
Request | |
Response |
To update, let's follow the URL pattern we defined with the pk of the song we want to update. We can use PUT or PATCH. The info you're sending should be in the Body of the request, just like it was for our POST request.
Request | |
Response |
Let's do the same thing for our deleteSong view, but let's delete Taylor's song this time (pk: 2). I'm sure it was no good anyways.
Request | |
Response |
Let's use our GET view to see what's inside the DB now:
**unimportant note: in my zeal to delete taylor's song I had a mishap and accidentally deleted song 3, which I have readded here using a post request. but it's id is now 5 :[
Finally, let's try out that "song with album" route. We'll add it to our urls.py:
# Probably not the best naming convention
path('songInAlbum', views.GetSongInAlbum.as_view(), name='Get song in album'),
Here's what our request will look like. ^^^^^^^^
Here's the response:
Good to know: Query Parameters Notice how our query params don't have to be specified in urls.py - they are dynamically generated from the URL that we try access (everything that comes after a ? in a url is a query parameter, with keys and values separated by '='. If you had multiple query parameters they would be separated by '&'. Next time you're browsing the web, notice how query parameters are used across the different websites you visit! It's easy to access query params within Django - see the getSongInAlbum view definition for an example. |
Authtokens, users, logins with Django REST Framework
Up to now, we've covered the fundamentals of how to create a database, populate it, and create simple endpoints for creating, updating, and destroying. But what happens when we want our system to be used by real users? How do we store their information and their interactions with our system? There are a few important issues that we'll need to address:
- How do we make sure that users' personal information like their passcodes are being stored in a secure way that protects them from being stolen?
- How do we build a system that users can sign up for and log in to? How do we store info about their session?
- How do we make certain endpoints in our system behave differently depending on the user who is accessing them?
The answer to these questions can be complicated. In order to save your time and energy, we're going to utilize the resources that Django and Django REST Framework provide for us as much as possible instead of developing our own solutions. Not only is this easier, but it's also much more secure- would you trust a system written from scratch by a novice undergrad student with your password and financial information?
How do we store user's personal info?
The answer to this question is usually to use Django's built-in User model. You can read the docs on User models here:
https://docs.djangoproject.com/en/3.1/ref/contrib/auth/
The User model contains common fields that will be used by users, and in your serializers you can define which fields are relevant to your use case.
By default, Django builds the User models for you. You can see them after you runserver and check inside the /admin route.
We can also utilize the User model to build new endpoints in our API, just like we could with any other model. Here's an example:
## Models.py
from django.contrib.auth.models import User
…
class UserLikesSong(models.Model):
user = models.ForeignKey(User, on_delete=models.CASCADE)
song = models.ForeignKey(Song, on_delete=models.CASCADE)
## Serializers.py
class UserLikesSongSerializer(serializers.ModelSerializer):
class Meta:
model = UserLikesSong
fields = ("id", "user", "song")
#Id of the rel, Id of the user, ID of the song
You can now make endpoints with this just like you would with any other model/serializer. This specific example could be used to track what songs the User likes, like in Spotify.
If you wanted to make a custom User model, you could read more about it here https://simpleisbetterthancomplex.com/tutorial/2016/07/22/how-to-extend-django-user-model.html and do more research, as there are many methods you could use. For basic university usage though, it's 99% of the time going to be faster and easier to roll with the User model they give you out of the box.
If you want to give different categories of users different permissions, see the permissions section (TODO: this won't be done for a while. In the meantime, these links may help: https://www.django-rest-framework.org/api-guide/permissions/ ← Technical overview
https://www.django-rest-framework.org/tutorial/4-authentication-and-permissions/ ← Basic usage example)
Signup, Login, Sessions: How do we do them?
I highly recommend using Django REST Framework's Authtokens to handle information about user sessions. You can read about authtokens, as well as the other options available, here: https://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication
To add Authtoken's, make sure the following items appear in settings.py:
###### You will need to add the REST Framework part.
###### INSTALLED_APPS should already exist.
REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': [
'rest_framework.authentication.TokenAuthentication',
],
}
INSTALLED_APPS = [ # There will be more here
'rest_framework',
'rest_framework.authtoken',
]
Note: I couldn't get these to work, at least not with authtoken. Leaving them here in case some enterprising individual finds them useful, or message us on Discord if you figure this out :) To get REST Framework's default login and logout views (prebuilt), type this in your project's root urls.py file: urlpatterns = [ ... path('api-auth/', include('rest_framework.urls')) ] Your path doesn't have to be api-auth, it can be whatever you want. |
To use REST Framework's login view, include this in urls.py:
path('whateverPathYouWantToLogin', obtain_auth_token, name='API Token Login'),
Include this at top of your urls.py:
from rest_framework.authtoken.views import obtain_auth_token
When you access this path and provide a real username and password in the request body, then you should receive an authtoken. This authtoken is associated with your account. Store this authtoken in a safe place. Now, you can use it in the "authorization" section of your next HTTP requests, and all requests you make from the client will be associated with the account you just logged in from.
Creating views for signing up is more difficult.
In serializers.py: from django.contrib.auth.models import User class RegisterSerializer(serializers.ModelSerializer): class Meta: model = User fields = ('id','username','password')#Change fields if u want extra_kwargs = { 'password':{'write_only': True}, } def create(self, validated_data): user = User.objects.create_user(validated_data['username'], password = validated_data['password']) return user This serializer will make sure that the password that the user makes is valid, and that it's write-only for security purposes. Choose which fields us |
In views.py: from django.contrib.auth import get_user_model # If used custom user model from rest_framework import permissions #We'll discuss more about perms later … class RegisterUserView(generics.CreateAPIView): model = get_user_model() #Will get the right one if you use custom permission_classes = [ permissions.AllowAny # Or anon users can't register ] serializer_class = RegisterSerializer #What we defined above |
In urls.py: path('register', views.CreateUserView.as_view(), name='Register user'), (you may want to put your register / login views together in a different Django App (so they are in a distinct section of your API) |
Test Request in Postman: Response from request: |
Now let's quickly do a login from this user we just created!
I did a login request to the login view I made earlier, but here's what I got:
Whenever you see an error like "no such table", that should be a clue that you need to rerun migrations. The app expected there to be a SQL table, but there was none made yet! Running migrations will ensure there is. Recall the commands for migrations are:
>> python manage.py makemigrations yourAppName
>> python manage.py migrate
In this case, just the second command will be sufficient
Request:
Response:
Yay! It worked! Now we can include this token in our request headers to associate all future requests made with the user we logged in.
In future requests, you should put the token as a value in your request headers, using the key: token.
Depending on the front-end you build, you should use a different way to store the authtoken that you get from logging in. Usually storing in local memory is okay. Do your own research for how to store authtokens with whatever system you are using.
If you want to improve security further, you can use JWT (JSON webtoken) instead, following the instructions here: https://simpleisbetterthancomplex.com/tutorial/2018/12/19/how-to-use-jwt-authentication-with-django-rest-framework.html
How do we make endpoints behave differently depending on which user is accessing them?
If a user makes a request while they are authenticated (using authtoken, or some other alternative method), then the system will automatically know what user is associated with the user who made the request.
You can access the user within a class-based view through
self.request.user
You can use this within your views in a variety of ways: to filter, to make more complex queries, and to check if the user should have access.
For example, let's make a UserLikesSong endpoint that is limited to the songs that the currently logged in user has liked.
class GetUserLikesSongs(generics.ListAPIView):
def get_queryset(self):
queryset = UserLikesSong.objects.all()
queryset = queryset.filter(user=self.request.user)
# Leftside of filter: from queryset. Rightside: how we're filtering
return queryset
serializer_class = UserLikesSongSerializer
We'll cover this in much more detail in the Permissions section.
Permissions
NOTE: Everything past here is incomplete - you will need to supplement it with your own research, like I did to make this guide! |
To use generic permissions with Django, all you need to do is:
- In your views.py:
from rest_framework.permissions import IsAdminUser, IsAuthenticated, IsAuthenticatedOrReadOnly
Now, on any class-based view you want to guard with permissions, you can add the following line:
class deleteLicenseType(generics.DestroyAPIView):
permission_classes = [IsAdminUser]
queryset = License_Type.objects.all()
serializer_class = License_TypeSerializer
(this is from a different project)
You can apply multiple permissions to the same view like this:
permission_classes = [IsAdminUser|IsAuthenticatedOrReadOnly]
Sessions & Cookies
Sessions/cookies are very easy to make use of with Django. You can use cookies to store information in a user's browser that you'll be able to access in all subsequent requests that a user makes. One example of a good use of sessions/cookies is to store a user's shopping cart content.
Some great videos for learning about sessions & cookies:
https://www.youtube.com/watch?v=C75IW38hKI8
https://www.youtube.com/watch?v=RjykNmVdcgI
Deploy to Heroku
To get your projects online, you can deploy them to Heroku. Heroku is just one of several possible hosting services for Django- but it's base tier is free, easy to use, and simple to deploy to, so that's what I recommend you use. The biggest downside of using Heroku is that its free tier will automatically shut down your app after a period of downtime, meaning it'll take a long time to respond the next time you try to access it.
A guide on getting started:
https://devcenter.heroku.com/articles/django-app-configuration
Some useful commands:
>> pip install gunicorn
To deploy to Heroku, you will need to make a file called Procfile (no file ending), and add the following gunicorn text to it:
web: gunicorn yourAppName.wsgi
This gunicorn file should be at the same level as your manage.py file. When you deploy to Heroku, you should be deploying from this level of the project hierarchy to avoid issues.
Your remote heroku environment needs to understand what requirements it will need to have to start up. You can do this by providing it with a requirements.txt file which will also be at the same level as your manage.py file.
To get the right requirements in a .txt file, type
>> pip freeze > requirements.txt
These commands will help initialize your heroku repository:
>> heroku create
>> heroku run python manage.py migrate
>> heroku run python manage.py createsuperuser
Important: Your database itself will not transfer to Heroku. You will need to recreate all entities, config, and users.
\ No newline at end of file diff --git a/guides/Django_Guide/images/image1.png b/guides/Django_Guide/images/image1.png new file mode 100644 index 0000000..c2dc3dd Binary files /dev/null and b/guides/Django_Guide/images/image1.png differ diff --git a/guides/Django_Guide/images/image10.png b/guides/Django_Guide/images/image10.png new file mode 100644 index 0000000..7e1259b Binary files /dev/null and b/guides/Django_Guide/images/image10.png differ diff --git a/guides/Django_Guide/images/image11.png b/guides/Django_Guide/images/image11.png new file mode 100644 index 0000000..06dbb24 Binary files /dev/null and b/guides/Django_Guide/images/image11.png differ diff --git a/guides/Django_Guide/images/image12.png b/guides/Django_Guide/images/image12.png new file mode 100644 index 0000000..49db837 Binary files /dev/null and b/guides/Django_Guide/images/image12.png differ diff --git a/guides/Django_Guide/images/image13.png b/guides/Django_Guide/images/image13.png new file mode 100644 index 0000000..9161cbb Binary files /dev/null and b/guides/Django_Guide/images/image13.png differ diff --git a/guides/Django_Guide/images/image14.png b/guides/Django_Guide/images/image14.png new file mode 100644 index 0000000..2c27cf4 Binary files /dev/null and b/guides/Django_Guide/images/image14.png differ diff --git a/guides/Django_Guide/images/image15.png b/guides/Django_Guide/images/image15.png new file mode 100644 index 0000000..12e2a36 Binary files /dev/null and b/guides/Django_Guide/images/image15.png differ diff --git a/guides/Django_Guide/images/image16.png b/guides/Django_Guide/images/image16.png new file mode 100644 index 0000000..160f9db Binary files /dev/null and b/guides/Django_Guide/images/image16.png differ diff --git a/guides/Django_Guide/images/image17.png b/guides/Django_Guide/images/image17.png new file mode 100644 index 0000000..568218d Binary files /dev/null and b/guides/Django_Guide/images/image17.png differ diff --git a/guides/Django_Guide/images/image18.png b/guides/Django_Guide/images/image18.png new file mode 100644 index 0000000..ad52aa4 Binary files /dev/null and b/guides/Django_Guide/images/image18.png differ diff --git a/guides/Django_Guide/images/image19.png b/guides/Django_Guide/images/image19.png new file mode 100644 index 0000000..edca256 Binary files /dev/null and b/guides/Django_Guide/images/image19.png differ diff --git a/guides/Django_Guide/images/image2.png b/guides/Django_Guide/images/image2.png new file mode 100644 index 0000000..a8b2956 Binary files /dev/null and b/guides/Django_Guide/images/image2.png differ diff --git a/guides/Django_Guide/images/image20.png b/guides/Django_Guide/images/image20.png new file mode 100644 index 0000000..1944723 Binary files /dev/null and b/guides/Django_Guide/images/image20.png differ diff --git a/guides/Django_Guide/images/image21.png b/guides/Django_Guide/images/image21.png new file mode 100644 index 0000000..c98ca33 Binary files /dev/null and b/guides/Django_Guide/images/image21.png differ diff --git a/guides/Django_Guide/images/image22.png b/guides/Django_Guide/images/image22.png new file mode 100644 index 0000000..c3587b1 Binary files /dev/null and b/guides/Django_Guide/images/image22.png differ diff --git a/guides/Django_Guide/images/image23.png b/guides/Django_Guide/images/image23.png new file mode 100644 index 0000000..cd9a988 Binary files /dev/null and b/guides/Django_Guide/images/image23.png differ diff --git a/guides/Django_Guide/images/image24.png b/guides/Django_Guide/images/image24.png new file mode 100644 index 0000000..1eed90b Binary files /dev/null and b/guides/Django_Guide/images/image24.png differ diff --git a/guides/Django_Guide/images/image25.png b/guides/Django_Guide/images/image25.png new file mode 100644 index 0000000..38bb54c Binary files /dev/null and b/guides/Django_Guide/images/image25.png differ diff --git a/guides/Django_Guide/images/image26.png b/guides/Django_Guide/images/image26.png new file mode 100644 index 0000000..8fa6fbc Binary files /dev/null and b/guides/Django_Guide/images/image26.png differ diff --git a/guides/Django_Guide/images/image3.png b/guides/Django_Guide/images/image3.png new file mode 100644 index 0000000..00bbd2d Binary files /dev/null and b/guides/Django_Guide/images/image3.png differ diff --git a/guides/Django_Guide/images/image4.png b/guides/Django_Guide/images/image4.png new file mode 100644 index 0000000..f1f1d0e Binary files /dev/null and b/guides/Django_Guide/images/image4.png differ diff --git a/guides/Django_Guide/images/image5.png b/guides/Django_Guide/images/image5.png new file mode 100644 index 0000000..34d45f4 Binary files /dev/null and b/guides/Django_Guide/images/image5.png differ diff --git a/guides/Django_Guide/images/image6.png b/guides/Django_Guide/images/image6.png new file mode 100644 index 0000000..df82768 Binary files /dev/null and b/guides/Django_Guide/images/image6.png differ diff --git a/guides/Django_Guide/images/image7.png b/guides/Django_Guide/images/image7.png new file mode 100644 index 0000000..21c6f71 Binary files /dev/null and b/guides/Django_Guide/images/image7.png differ diff --git a/guides/Django_Guide/images/image8.png b/guides/Django_Guide/images/image8.png new file mode 100644 index 0000000..1068a4c Binary files /dev/null and b/guides/Django_Guide/images/image8.png differ diff --git a/guides/Django_Guide/images/image9.png b/guides/Django_Guide/images/image9.png new file mode 100644 index 0000000..6539748 Binary files /dev/null and b/guides/Django_Guide/images/image9.png differ diff --git a/guides/Git_Guide/GitGuide.html b/guides/Git_Guide/GitGuide.html new file mode 100644 index 0000000..f2ef5e6 --- /dev/null +++ b/guides/Git_Guide/GitGuide.html @@ -0,0 +1 @@ +
Tech Start's Git Guide |
Legend
=== Beginner Section ===
- Getting Started
- Staging Files & Commits
- Big Picture & Git Analogy
- Staging Files & Creating Commits
- Branches
- Remote Repositories
- Merge Conflicts
- Using Github
- Our Recommended Git Workflow
- FAQ
=== Advanced Section ===
- Advanced Staging & Commits
- Git Stash
- Git Clean
- Undoing Commits & Changes
Unless otherwise noted, all git commands are one line terminal commands
We are also assuming that you have set up a project at /path/to/project and had “cd’ed” to /path/to/project
Getting Started - Setting up a Repository
https://docs.github.com/en/enterprise-server@2.22/get-started
A Git Repository is virtual storage of your code, allowing you to save versions of your code, as well as share and allow others to edit the code.
Initializing a new repository: git init
- This step is typically used by the project manager, or the owner of the project
Cloning an existing repository: git clone [github git link]
- This step is typically used by the project members, or anyones who wants to add onto the projects after it has already been created
- The github git link can be located on the github repository website under the clone dropdown
Big Picture & Git Analogy
Imagine that we have two people working on the same paper remotely, Person A and Person B. Now we notice that Person B is the laziest of the two, so Person A starts the paper.
Since they are unaware of Google Docs, Person A choses to create a word document on their local machine. This can be seen as Initializing a new repository.
After working on the paper for a bit, he realizes that Person B also needs to contribute, so they send the paper by email to Person B. This step is equivalent to forking a repository.
Person B decides that he would prefer to work on the paper by hand, and so he takes the email that Person A sent, and prints it to work on, cloning the repository
Staging Files & Creating Commits
Git works using units of change called commits. These commits are essentially snapshots of your project. To share any changes, additions, and deletions that you make with other people and upload it to the internet, you will need to package them into a commit first.
The process of staging files to create a commit is like an assembly line at a factory. The final product of this process is a commit, and you can use commands like
You can think of the staging area of git (the green box that says "staged changes" in the below diagram) like a box. You can add and remove changes from the box on a per-file-basis.
Committing is like sealing that box and sticking a label on it. The contents of that box are your changes. But, if there are changes in the untracked or unstaged areas, they will not be included in the commit, because they are outside of the box.
The following diagram shows how the staging process works, and what commands you can use to move changes on a per-file-basis in between areas. Use the git status command to see a summary of where every change in your project is on this diagram! We recommend using git status frequently.
Shown are some common commands for using git to store and prepare the code to be pushed to the remote repository. They are shown in the general order that you want to use them in.
Below is the legend for some common, optional parameters which are shown
- (-text) = optional parameters for command, which are called as is (git command -text)
- [textName] = optional parameters for command, which are called with your version of the name (git command helloWorld)
git status | Shows the status of all changes (changes that have been staged, NOT been staged, or NOT yet been committed). It shows where every change is on the diagram above, and even lists some helpful commands. It will also say what branch you are on, and if you are ahead or behind the remote version of your branch in terms of commits (more on this in later sections). Additionally, if you have a merge conflict, it will show which files caused it. |
git add [file path] | selects the specified files, moves it to the “staging area” and includes it in the next commit This command will also allow adding a deleted file to be staged, which after being committed and pushed will remove the file from the git branch **This command will ignore all files in the “.gitignore” file **
|
git commit -m “[commitMessage]” | Creates a new commit that includes all changes that you added to the staging area. You always need to include a name for your commit. It is helpful to be as descriptive as possible! If you don't use the -m flag and provide a commit message in quotations, git will make you write a commit message using a text editor. However, this can be very confusing for people especially since your default git text editor is often configured to be VIM (if it is, you can type :qa to exit). For this reason, we recommend always specifying the commit message using -m. After you commit, these changes are no longer in the staging area- they are in your commit!
|
git restore [file path] | Discards local changes in a file, thereby restoring its last committed state. You can use it to quickly get rid of accidental or unnecessary changes, restoring your files to how they used to be before you changed them. It won't work if your file is already staged - you'll have to unstage it with git restore --staged first. |
git restore --staged [file path] | Removes the file from the Staging Area, but preserve all modifications you made to it. You can use it if you accidentally added a file to the staging area whose changes shouldn't be included as part of the next commit you are planning to make. If the file was originally untracked, it becomes untracked again. If it was originally a file with unstaged changes, the changes become unstaged again. |
Naming commits
When you create a commit, you always want to include a descriptive name for the commit that describes exactly what it accomplishes. You wouldn’t label a moving box with kitchen items as simply “stuff.”
For a video tutorial on staging files, watch https://www.youtube.com/watch?v=KngvG8WzYLU&ab_channel=TheNetNinja
If you want to learn about additional flags and commands you can use in the process of staging files and adding commits, see the section Advanced Staging & Commits
Branches
Branches represent an independent version of the code. They allow new features to be worked on, while ensuring that a working version of the code is not tampered with. This allows large changes to be made to the code base, with little fear of breaking larger projects.
git branch | Lists all branches in the current repository |
git branch [branchName] | Creates a branch called branchName in the current repository. The created branch's commit history will match the branch you were on when you called git branch. We recommend naming branches according to what you want your branch to do. For example, if I was updating the font on a website, I might call my branch updateFont. You may also want to add a prefix to the branch name to indicate it is your branch (this is optional- example, I could call my branch joel/updateFont.) |
git branch -d [branchName] | Deletes the branch called branchName (You can use -D instead of -d to force delete the specified branch, even is it has unmerged changes. It's typically better to use -d, unless you are 100% sure you will never need the branch you are deleting again) |
git checkout [branchName] | Navigates your current directory to the specified branch, allows you to select which line of development you are working on. You can only switch branches if you have no unstaged/staged changes in your current branch. If you can't switch branches because of this, see What happens if you can't checkout? for more instructions. |
How should you use branches?
Whenever you are working on a new feature, or conducting a test/messing with code, you should create a new branch to use.
Before you make your branch, you should make sure you are creating your branch based on the most recent code. Do git checkout main (or master instead of main) to switch to the primary branch of your repository. You will also probably want to do git pull to make sure the primary branch is up to date with the version present on your remote repository (more on this in the next section).
Now that you are on the primary branch, use git branch [branchName] to create a new branch based on the current one. Make sure you name it according to what you aim to accomplish there (see the description of the command above).
Now that you have created your branch, you'll want to switch to it. Use git checkout [branchName] to switch to your branch. You can do work here and follow the instructions in the staging files and creating commits section to save your changes into commits.
Eventually, you'll be done using the branch (perhaps you will follow the instructions in the next few sections to push it to your remote repository and use it in a pull request. or perhaps you need to work somewhere else). Either way, you can switch to a different branch with git checkout [branchName].
If you have completed a pull request for your branch to merge it into a different branch of your project, you no longer need to keep the local copy of your branch. We recommend you use git branch -d to delete any branches you will no longer need to use. This makes sure your local repository remains nice and tidy.
What happens if you can't checkout?
Git will not let you checkout to switch branches if you have staged or unstaged changes.
You will have a few choices on what to do:
- Restore files to how they originally were (either by manually undoing, or by making use of git restore, described in the previous section). Do this if any of your changes are unnecessary or accidental.
- Create a commit, following instructions from the previous section. Only create a commit if you actually want to save the changes you made. We recommend you avoid making commits on any branches that you share with other people, especially your primary branch (main/master)!
- Utilize git stash to move changes from one branch to another without needing to commit them. Do this if your changes are intentional, but you wanted them on a different branch than the one you are currently on. This is described in more detail here.
You can combine these approaches to deal with your changes as necessary.
Remote Repositories
When you work with git, you will typically have a local repository (the copy of your project that exists on your personal device) and a remote repository (the copy of your project that exists on the internet, usually on a service like GitHub or BitBucket)
An absolutely core part of using Git is managing the interactions between your local repository and the associated remote repository. The two key commands you will need to learn are git push (which you can use to push commits from your local repository to the remote repository) and git pull (which you can use to pull commits from the remote repository and insert them into your own local repository). We have more info on how to use these commands appropriately below.
A common mistake that newcomers to git will make is assuming that the local repository is the same as the remote repository- when they're actually 2 separate concepts. Your commits won't appear on the remote repository until you manually push them there. If someone else pushes new changes to the remote repository, you won't see their changes on your local repository until you manually pull those changes to your device.
Most version control related work happens in a local repository(staging, committing, viewing status and logs). When you start working with others on the same project, is when remote repositories come into play. It is like a file server that you use to exchange data with others.
Local | Remote |
Are located on the computers of the team members | Are on the internet or a local network |
Contains branches, commits, tags | Contains branches, commits, tags |
All “coding work” happens only in the local repository, and needs to be made and committed locally. | After the work has been committed locally, it can be “uploaded” to the remote repository in order to share with others. |
Note: You can name a local branch the same name as the remote branch/repository, but they are NOT the same
Note: You can also have multiple remote repositories(default is origin). This allows you to have multiple different working branches for new/different features of your code.
git fetch is what you do when you want to see what everybody else has been working on. it doesn’t force you to actually merge the changes into your repository. This makes fetching a safe way to review commits before integrating them with your local repository.
https://www.git-tower.com/learn/git/ebook/en/command-line/remote-repositories/introduction/
git pull [remoteName] [branchName] | Pulls all changes/commits from the remote branch, and inserts them into your current branch More technical description: fetches from the remote branch (git fetch), and merges your current branch with commits from the remote (git merge) **You can “pull” before “pushing” to a branch to avoid unwanted merge conflicts and errors**
|
git pull origin main | fetches commits from the master branch of the origin remote (into the local origin/master branch), and then it merges origin/master into the branch you currently have selected |
git push | updates the remote branch with your staged, local commits **Always “pull” before “pushing” to a branch to avoid unwanted merge conflicts and errors** |
Make sure to PULL before every PUSH if you are collaborating with others.
Merge Conflicts
Conflicts generally arise when two people have changed the same lines in a file, or if one developer deleted a file while another developer was modifying it. In these cases, Git cannot automatically determine what is correct. Git will mark the file as being conflicted and halt the merging process. It is then the developers' responsibility to resolve the conflict.
Resolving merge conflicts is a completely normal part of working collaboratively
The general steps for resolving merge conflicts can be seen as:
- Figure out the conflicts and change them accordingly
- Re-commit the changes
- Attempt to merge with the selected branches
- Read error messages (if any) and repeat if necessary
Some useful commands for attempting to fix merge conflicts
git status | Help identify conflicted files |
git log --merge | Produces a log with a list of commits that conflict between the merging branches |
git diff | Finds the differences between the states of a repository, which helps in preventing conflicts |
git reset --mixed | Undo changes to the working directory and staging area |
Example of Merge Conflicts shown in Command Line
In this case, there are two instances of the file “merge.text” that were modified by different branches/people. Git is unable to determine which lines to keep, as both were changed manually.
Using GitHub
GitHub is a company that provides a service of hosting git repositories online. There are many other alternative companies that provide a similar service, like BitBucket, GitLab, and Azure DevOps, but GitHub is the most popular one and we recommend using it in this club.
The instructions for the rest of this section will focus on GitHub's features. However, almost every feature described here has equivalents in the other git hosts, so if you know how to use one you generally know how to use them all.
Pull requests
Video intro to pull requests:
https://www.youtube.com/watch?v=2VX1ISk9XH8&ab_channel=GitKraken
A pull request is a way of merging code from one branch of your remote repository into another.
You are requesting that the base branch pulls the commits from the compare branch. In the above example, you are requesting that the main branch pulls the commits from the addLaunchEvent.
We recommend you use pull requests extensively as part of your git workflow.
We encourage teams to use small, frequent, single-feature PRs. Each PR should have a name that describes exactly what the PR accomplishes. By doing smaller PRs, you will make sure everyone frequently updates their codebase so you don't end up with massive merge conflicts. By limiting your PR to a single feature, you also make it super easy to roll back that feature and reverse all commits in the PR by reverting the PR itself.
Sometimes, when you create a pull request, it will say there is a merge conflict. If this happens, don't force the PR to merge! Instead, you'll want to resolve the merge conflict. Steps:
- On your local machine, checkout to the "compare" branch -
(ex. git checkout addLaunchEvent)
- Once you are on the compare branch, do a git pull from the base branch of your PR
(ex. git pull origin main)
- This will pull changes from the base into your compare branch. Git will notify you that this caused a merged conflict. This is okay!
- Resolve the merge conflict according to the instructions in the Merge Conflicts section. You'll need to add and commit the files where you solved the merge conflict.
- Confirm you have resolved every merge conflict. Try running/building your app again to make sure everything works as expected.
- Push the commit(s) that solved the merge conflict to your remote compare branch.
(ex. git push origin addLaunchEvent)
- The pull request should now update saying there is no merge conflict! You can merge it now, as long as your team approves of it.
Advantages of pull requests:
- They enable your team to do pull request reviews (see more below)
- Your team can set up custom tests / deployments using CI/CD methods to ensure that your code runs as expected before you merge it
- It enables you to double check what code you are adding
- If you ever need to undo a pull request, it's very easy. Most git hosts have an easy way of reverting a pull request- usually it will create a new branch and PR itself, from which you can solve any merge conflicts and quickly roll back the code added from a previous PR.
- If you stick to coding 1 feature per pull request, it makes it very easy to understand the history of your repository
Additional readings on pull requests:
https://product.hubspot.com/blog/git-and-github-tutorial-for-beginners
https://yangsu.github.io/pull-request-tutorial/
Pull Request Reviews
One of the main advantages of pull requests is that they enable you to do a pull request review, ensuring that code that gets pulled into your primary branches has been reviewed by your team to make sure it won't introduce code smells or bugs.
PRs provide the opportunity to review another developer's code and make sure that it meets the guidelines or practices that your organization or team has. For example, if you have a developer who is more familiar with the architecture of the software system, they can provide valuable input towards making sure that your changes fit within the long term architectural vision of the system. Alternatively, you can have a newer team member who is not yet familiar with the overall code structure and they can add comments to specific parts of the code in a PR to ask for further clarification for why a certain change was made. PRs have been an essential learning tool for me during the past 10 months of my internship.
Aside from learning, PRs generally serve as a major communication channel for developers in industry, because they provide the opportunity for automated testing and improvements before your code changes are moved to the next deployment stages. One example of automated testing is using linter which is a static code analysis tool used to flag errors in your code such as bugs, stylistics errors, and suspicious constructs, like for example declaring a variable twice.
Whenever someone wants to merge a pull request, you should require them to get their PR reviewed first. To review a pull request, look at all the changes they made.
Best Practices for PR Contributors:
- Review your PR before adding reviewers.
- You may find some work-in-progress or experimental code. There could also be a typo, unintended indentation, or extra line breaks.
- Link your PR to your issue/ticket.
- Include a brief description of your changes
- Push small incremental commits to your PR.
- You can also mark your PR as a DRAFT PR in GitHub. This pre-commit review can be good practice to check with reviewers if you are going in the right direction before making any more code changes.
- Add additional comments to your PR to guide reviewers through the review.
- Highlight areas reviewers should focus on.
- Clarify changes with comments and additional references.
- Favor adding code comments over PR comments as the code comments will out survive the PR comments.
Best Practices for Reviewers
- Be fast, not furious
- Responsiveness and turnaround time are very important to keep PRs healthy and not go stale due to other changes which may have been merged during the time that the PR is open and may even introduce new merge conflicts.
- Either as a reviewer or as an author, you should keep the conversation actively going until the issue is resolved.
- As a rule of thumb, if the PR is small or trivial, you should review it within one business day.
- Plus, context switching is very expensive in industry. Many developers, like myself, have the memory of a goldfish when it comes to remembering the code we wrote a day ago. So, as a courtesy, you can let the developer who opened the PR know if you are planning on looking at their PR at a later time. If there are PRs open, it is also good practice to review them before you create a new one yourself.
- If there are outstanding comments or the PR is in draft mode, do not approve the PR.
- Instead, stay involved and follow the discussions and new changes to see how the PR pans out.
- Do NOT rubber stamp reviews.
- If you do not understand a change, you can ask for clarification or justification in the comments.
- You do not have to approve a PR if you are not actually approving the change. You can let the author know that you have completed your review but are not weighing in on the approval.
- Our TechStart website team's default PR policy requires approvals from 2 different reviewers, but an approval that is rubber stamped can be more harmful than abstaining if it promotes bad practices and bugs to be user-facing.
- Provide constructive comments
- Code reviews are an important step in ensuring we build high-quality software products. As a reviewer, it's your job to carefully read and think about the code you are reviewing, and provide constructive feedback or ask questions about the code if things are unclear.
- If the code isn't formatted correctly, too confusing, contains mistakes, or follows poor conventions, leave a comment to tell them what they did wrong and how they might be able to fix it (but phrase everything constructively! you don't want to seem rude or aggressive).
- If you disagree with something, give a reason and an example of a better solution. Let the author know exactly what you think is better.
GitHub and other git hosts support adding inline comments, so you can comment on specific areas of the code when necessary. The best place to do this is the "Files Changed" tab of a pull request.
It is up to them to address every issue that is brought up, and push the changes back to their branch. They should let you know when they've completed everything, and you can check to make sure you're happy with their changes.
Issues
GitHub Issues are a great way of keeping track of tasks, bugs, and goals for your projects. We recommend using them as the primary way of assigning tasks to your team and planning out your dev work.
You can read more about issues here:
https://guides.github.com/features/issues/
Our recommended Git workflow
TODO: Describe how a team of developers should use branches to do versioning correctly
TODO: Describe possible failures that a developer may encounter in this process because of mistakes they made, and how to recover from them
Let's assume you have some commits on branch yourLocalBranch, and you want to merge them into a branch on your team's GitHub (which uses the default remote alias, origin) called branchYouWantToMergeTo.
Part 1 - Set up your branch
- Ensure you are on the main branch of your repository. It is usually called main or master. If you are not on the main branch, switch to it with git checkout main (or master)
- Pull the most recent version of your main branch from GitHub. You can do this with git pull origin main (or master). This will make sure your new branch contains all the most recent changes
- Create a new branch for yourself. The name of the branch should describe what the code inside will do, and you should prefix it with your name or nickname. For example, git branch joel/changeButtonColor
- Check out your new branch before you make any changes. Refer to Branches if you make any mistakes. Example: git checkout joel/changeButtonColor
Part 2 - Make your commits
- Follow the instructions in the Staging Files and Adding Commits section to create a commit containing your desired changes. Use git status frequently to make sure you are doing everything correctly.
Part 3 - Push your commits to origin
- Push your branch to origin. Ex. git push origin joel/changeButtonColor
- Set up a pull request on GitHub, with the base as main (or the branch you want to merge to) and the compare branch as your branch, (ex joel/changeButtonColor)
- (Only if your pull request indicates you have a merge conflict): DO NOT merge the branch. Instead, do git pull origin main (or the branch you want to merge to) on your local machine. This will bring up the merge conflict.
- Follow the instructions in "Merge Conflicts" to fix any merge conflicts that you get from pulling that branch. Once you have fixed all merge conflicts, remember to double check that your code runs, then git add and git commit your fixes!
- Push your changes to your remote repository! Do git push origin yourLocalBranch
- Now that your changes are present on your remote repository, you should create a pull request on GitHub. The base (target branch) should be branchYouWantToMergeTo, and the source should be yourLocalBranch.
- Check to make sure the pull request says "No merge conflicts". If it does detect merge conflicts, that means you didn't do steps 4-7 correctly, so redo them!
- Request a reviewer for your pull request. They will read your code and offer suggestions on how to improve it.
- Resolve the comments of your reviewer. Once they are resolved and your reviewer confirms you can proceed, you can merge the pull request on GitHub. Congratulations! your code is now merged into your project.
Clean up
- Delete your branch on the remote repository
- Delete your branch on your local system (checkout to main. Then delete with git branch -d yourBranchName)
Big Picture Git/GitHub Workflow
Now that you understand the complete process on an individual level, let's take a step back to understand how your team will be using git.
Here is the Git workflow we recommend:
(This is what is used at Microsoft. It works well and it's good practice to teach it)
- When a team member wants to make changes or additions to the code, they should create a new branch for themselves. The branch name should describe what it does, ex. "fixButtonGlitch"
- They push their code to a branch on your origin repo that shares the same name
- When they're ready, they create a Pull Request on GitHub. The PR's source should be their branch, and the destination should be either master or main (whichever your repo is using).
- They should describe their Pull Request in the description and provide screenshots if applicable
- They merge their own PR, once the following 3 conditions are met:
- There are no merge conflicts with the base branch
- If your project has Continuous Integration (which it should), the PR build succeeds
- At least 2 people have reviewed the code in the PR (more on code reviews later) and all comments from code reviews have been resolved
- Upon merging the PR, they delete their branch.
FAQ
List of questions that Joel got often:
What should I do if I made a commit in the wrong branch?
Refer to undoing changes and commits
What should I do if I started work in the wrong branch but not committed yet?
Refer to undoing changes and commits
What if I want to revert a commit?
Refer to undoing changes and commits
How do I push code from my local branch to a remote branch that has a different name?
- In order to push your branch to another remote branch, use the “git push” command and specify the remote name, the name of your local branch as the name of the remote branch
How do I create a new local branch based on a pre-existing remote branch?
https://www.git-tower.com/learn/git/faq/checkout-remote-branch/
What do I do if my pull request says it has merge conflicts?
Advanced Section
Here are some advanced git commands you can use to boost your git game to the next level. They are not essential to using git, but you may find them helpful. If you're still learning the beginner commands, we recommend focusing on them until you're comfortable with them before worrying about these advanced commands.
Advanced Staging and Commits
Here are some additional commands and flags for existing commands that you can use while you are staging files and adding commits.
If you want descriptions of the basic staging and commits, please see staging files & creating commits in the beginner part of the guide.
git status (-s) (-v) | You can use the -s and -v flags on git status for the following effects:
|
git add [fileName or folderName] (-u) | You can use the -u flag on git add for the following effects:
|
git commit (-a) (-am) "[Commit message here]" | You can use the -a and -am flags on git commit for the following effects:
|
Git Stash
https://www.atlassian.com/git/tutorials/saving-changes/git-stash
WIP, should include push, pop, apply, list
Git Clean
WIP, should include push, pop, apply, list
== didnt realize we already have git clean there, but we can do more detail here ==
Undoing Commits & Changes[a]
WIP
Below is the general sequence of commands to check, and undo previous commits. Notice that we must use the commit comments as the easiest factor in differentiating between commits. It is important to use a descriptive comment for each commit.
git log | Displays old commits with the ID hash and commit comment on the current branch |
git checkout [id hash] | Will make your working directory match the exact state of the id’ed commit *nothing you do here will be saved to the current state of the project (to go back do “git checkout main”) |
git clean (-f) (-n) | ‘git clean -n’ shows which UNTRACKED files will be removed, should you do ‘git clean -f’ ** good practice is to always -n before you -f **
|
git revert | Undos a single commit |
git reset [id hash] | Goes back to specified commit by removing all subsequent commits |
Git Rebase and Git Merge
WIP
git merge [branchName] | Merges the specified branch into the branch that your local directory is currently on. In a typical workflow, you will not need to use this command ever. Instead, git pull and pull requests will handle all merging for you. |
[a]Before thursday:
I will do touchups to all the beginner sections
Could you include an example in the merge conflicts section of how to solve a merge conflict?
Then let's add a little more for git stash because we might need push and pop when people inevitably make mistakes
Tech Start's API Guide |
APIs are a ubiquitous component of software engineering. APIs allow different components of a software system to interact with each other in a logical way.
Learning about APIs is critical to your growth as a software developer. This guide contains links and advice to get you started!
Introduction
What is an API?
API stands for Application Programming Interface, and in simple words, allows two applications to talk to each other and send information between the two.
Further reading on the basics of APIs: https://www.plektonlabs.com/api-101-what-are-they-and-how-do-they-work/?gclid=Cj0KCQiAhf2MBhDNARIsAKXU5GRbLqWDWBPN0Zh4ZX6KwjevURl9KmQo0EVBzLn5mcePxaI_l1oWQSQaAkGDEALw_wcB
Analogy of an API
Imagine you are sitting in a restaurant with a menu and you are trying to decide what to order. You are one of the applications and in order to get food, the kitchen will act like the other application. It is the system that will “make” you food. The waiter in this scenario will be the API, and he/she delivers the food from one application(the kitchen) to another(you). The waiter is the messenger that takes your request or order and tells the kitchen – the system – what to do. Then the waiter delivers the response back to you; in this case, it is the food.
How API’s Work
- A client application initiates an API call to retrieve information—also known as a request. This request is processed from an application to the web server via the API’s Uniform Resource Identifier (URI) and includes a request verb(see Types of API calls), headers, and sometimes, a request body.
- After receiving a valid request, the API makes a call to the external program or web server.
- The server sends a response to the API with the requested information.
- The API transfers the data to the initial application that requested the information.
Why would you need an API?
Many companies have APIs built to allow others to build interesting applications using their company data. APIs also allows a project to be dynamic - it will update the frontend information automatically when the back end is updated. This saves the hassle of going through tons of HTML code updating data one by one.
Types of APIs
GraphQL vs Rest
Reading In favor of GraphQl:
https://www.howtographql.com/basics/1-graphql-is-the-better-rest/
Reading In favor of Rest:
https://www.rubrik.com/blog/technology/19/11/graphql-vs-rest-apis
Rest APIs
About
https://www.ibm.com/cloud/learn/rest-apis
A REST API is an API that conforms to the design principles of the REST, or representational state transfer architectural style. For this reason, REST APIs are sometimes referred to RESTful APIs.
What is a RESTful API? https://www.youtube.com/watch?v=y0U-ZxgLu98
Types of API calls
Creating your own API
Interactive Resource on APIs
https://apiary.io/how-to-build-api#phase-design
Tons of help on creating API with different languages https://rapidapi.com/blog/20-tutorials-on-how-to-create-your-own-api-sorted-by-programming-language/
Explanations of API’s and more in depth language-specific resources
https://www.moesif.com/blog/api-guide/getting-started-with-apis/
Using Postman
What is Postman?
Postman is a platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs faster.
Getting Started with Postman: https://www.guru99.com/postman-tutorial.html#1
Good Postman Series starting with setting up: https://www.youtube.com/watch?v=juldrxDrSH0&ab_channel=AutomationStepbyStep
Further Resources on APIs
Collection of Free, premade API’s
*Most premade API’s will have documentation of how to use/maintain them*
https://github.com/public-apis/public-apis
Example of using a premade API
https://rapidapi.com/blog/how-to-use-an-api/
GraphQL
Further Help
GraphQL Tutorial: https://www.youtube.com/watch?v=ed8SzALpx1Q&ab_channel=freeCodeCamp.org
What is GraphQL (A really good article): https://www.redhat.com/en/topics/api/what-is-graphql
Why use GraphQL: https://www.apollographql.com/docs/intro/benefits/
Getting started with GraphQL: https://www.apollographql.com/docs/intro/benefits/
GraphQL is split into two main parts, A Schema (Basically a model for the response), and a resolver (a collection of functions that generate response for a GraphQL query. In simple terms, a resolver acts as a GraphQL query handler)
An article that explains what a Query, Mutation & Subscription are: https://medium.com/software-insight/graphql-queries-mutations-and-subscriptions-286522b263d9
\ No newline at end of file diff --git a/guides/GraphQL_API_Guide/images/image1.png b/guides/GraphQL_API_Guide/images/image1.png new file mode 100644 index 0000000..76be96f Binary files /dev/null and b/guides/GraphQL_API_Guide/images/image1.png differ diff --git a/guides/GraphQL_API_Guide/images/image2.png b/guides/GraphQL_API_Guide/images/image2.png new file mode 100644 index 0000000..b2ba6f9 Binary files /dev/null and b/guides/GraphQL_API_Guide/images/image2.png differ diff --git a/guides/GraphQL_API_Guide/images/image3.png b/guides/GraphQL_API_Guide/images/image3.png new file mode 100644 index 0000000..381060e Binary files /dev/null and b/guides/GraphQL_API_Guide/images/image3.png differ diff --git a/guides/React_Guide/ReactGuide.html b/guides/React_Guide/ReactGuide.html new file mode 100644 index 0000000..66981a9 --- /dev/null +++ b/guides/React_Guide/ReactGuide.html @@ -0,0 +1 @@ +Tech Start's React Guide |
~~ WIP ~~
React Essentials
Check out this video as a crash course to React:
https://www.youtube.com/watch?v=Ke90Tje7VS0
If you find this video confusing, or prefer a different one as a React intro, please let us know :)
If you prefer reading to watching videos, this guide is helpful:
https://www.freecodecamp.org/news/the-react-handbook-b71c27b0a795/
Note on functional versus class-based components
When React was first created, class-based components were the standard. But functional components were introduced later, and they eclipse class-based components in every way.
Our advice: You should probably never use class-based components!
Stick to functional components. They are more modern and more versatile.
Lots of tutorial content online still uses class-based components. If you stumble upon a tutorial or explanation that uses a class-based component, and you're new to React, please search for a functional-component alternative instead!
Intermediate React
This section of the guide contains some topics you'll want to learn once you know the essentials of React.
React Hooks
In general, a good order of learning hooks is:
- useState: https://www.youtube.com/watch?v=4qVNaohzDWU&ab_channel=LogRocket
- useEffect:https://www.youtube.com/watch?v=gv9ugDJ1ynU&ab_channel=TheNetNinja
- useRef: https://www.youtube.com/watch?v=yCS2m01bQ6w&ab_channel=Codevolution
- useCallback: https://www.youtube.com/watch?v=-Ls48dd-vJE&ab_channel=BenAwad
Other built-in hooks exist, but their uses are more niche, and should only be learned when necessary.
Creating custom hooks
You can, and should, create custom hooks in React. Using custom hooks, you can encapsulate a bunch of complicated logic into a simple hook function call, and name it appropriately to describe what your custom hook accomplishes.
https://www.youtube.com/watch?v=Jl4q2cccwf0&ab_channel=TheNetNinja
Calling APIs - Part 1
Calling APIs is a key part of any React App. It's what enables your app to communicate with the outside world - including, presumably, your backend.
Here's a helpful tutorial on the best practices for calling APIs in React:
https://www.youtube.com/watch?v=bYFYF2GnMy8
There's also a part 2:
https://www.youtube.com/watch?v=1tfd6ANaNRY
The best ways to fetch data are using the popular package Axos (https://www.npmjs.com/package/axios) or the vanilla JS fetch function (https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)
Once you have parsed the data, you'll probably want to store it in your state somehow (using useState or a redux store).
It is also good practice to encapsulate your entire API call into a custom hook, and name the hook according to what it does (ex. useFetchPokemonStats). This is also much easier to do if you use a state-management system like Redux, which is described below.
Calling APIs - Part 2
The methods described above let you call an API immediately upon rendering a certain component. But what happens if you want to manually trigger an API call (ex. after a certain action or event)?
Your API call should still use useEffect, and should look mostly like the calls you learned about in Part 1. The 1 difference is you need to guard the useEffect wisely in its dependency array.
As you recall, the dependency array of a useEffect contains everything that the useEffect depends upon - if any of its dependencies change, it will have a side effect of rerunning the useEffect.
So, you can define a specific variable which only changes when you want your API call to run. You can put that variable in the dependency array of the useEffect. When the action or event that you want to trigger the API call occurs, you should change the trigger variable. This change will trigger the useEffect to run. The trigger variable should never change except when you want the useEffect to run.
I personally like making my trigger variable an object which also contains any subvariables that my API call needs. So for example, if I was coding a call to a search API that included a text query and target price, my trigger object would contain those.
Here is an example of a very basic React application that calls an API to perform a search with a custom hook and a useEffect guarded by a trigger object as described above: https://github.com/Tech-Start-UCalgary/react-api-examples/tree/main/js-no-redux
useSWR
useSWR is a useful React hook for data fetching published by Vercel (creators of Next.js).
SWR stands for stale-while-revalidate. It allows for smart data fetching and encapsulates a lot of advanced fetching logic (like how often should you refetch? should you have a cache?) in a single line of code.
You should read more about useSWR here:
You can watch a video tutorial here:
https://www.youtube.com/watch?v=f7yjEdXgGiM
React with Redux
Redux is a widely used state container for javascript apps. As soon as your app reaches any level of data complexity, it makes a ton of sense to start using Redux to manage your state.
A fair warning: Redux will seem complicated at the beginning. That's completely expected! Push through that initial discomfort and you'll get used to it in no time :)
Here is a great introductory video to React-Redux:
https://www.youtube.com/watch?v=CVpUuw9XSjY
I highly recommend using createSlice to setup your Redux Store. It is a simple way to encapsulate creating actions and slicers in a simple, easy-to-read, easy-to-understand way. Here is a short video that does a great job explaining how to use createSlice:
https://www.youtube.com/watch?v=e0MEtFaQTZk
To access your Redux state and update your Redux state in React, I highly recommend using the twin hooks useSelector and useDispatch respectively. They are simple, easy, and elegant.
https://www.youtube.com/watch?v=3zoIigieur0
~~ Joel will add a full example Redux App here eventually ~~
React Native
Legend
General[a]
Setup
First Project
JavaScript Basics
Variable
Arrow Functions
Classes[b]
Callbacks
Promises
Await/Async[c]
React Basics
Components
Props vs State
Events
Forms in React
Higher Order Components
Hooks
React Ecosystem
React Router
Redux[f]
Next.js
Setup
Prerequisites
In order to use create-react-app, you need to have Node.js installed. Node includes npm (the node package manager), and npx (the node package runner).
You should also have a code editor(like VS Code) installed.
First Project - Creating create-react-app
Make sure you cd to the place you'd like your app to live on your hard drive, then run the following in your terminal:
npx create-react-app name-of-your-app
Note: npx create-react-app will download some Node_Modules for you, but if you are getting a react project that is already made, you will need to type npm install in your terminal.
JavaScript Basics
Variables
Chakra UI is a great frontend ui framework, and it works well with React. Here's a tutorial series that teaches you the basics quickly:
https://egghead.io/courses/build-a-modern-user-interface-with-chakra-ui-fac68106
[a]@terryfu33@gmail.com
In general, this guide should have minimal in-guide
1, max 2 sentences explaining what a topic is, and why it should be learned, and then a link to a single good video/playlist which explains it. Good formatting is necessary too.
Should be a springboard to explanations, not an attempt to re-explain things
[b]Classes wont be necessary for React
[c]Async js is super helpful so it's good to have it here! We may want to include it at end instead of beginning though. Check if I added stuff to our web dev guide too
[d]The React Basics section can just be condensed to a single good video/playlist which teaches the essentials
[e]I think I covered almost all this in the intro section I added
[f]I got this
Tech Start's Super Awesome Mega Web Dev Guide :) |
Want to get into web dev? This guide should be your best friend. It covers some of the basic tools and languages you'll need to dive into the world of web development. Rather than providing tutorials, this guide focuses on directing you towards the best free online content to teach you the fundamentals.
Our advice:
- Go through at your own pace! You may need to spend more or less time on a particular topic depending on your experience level.
- Build practice websites and apps as you learn - you learn by doing.
- Take your own notes, especially for problems you encounter frequently
- Go beyond this guide! Tons of resources, courses, and tutorials are out there if you want to learn. Remember: google is a programmer's best friend.
This guide was originally developed for Tech Start UCalgary, an undergraduate club for software development and entrepreneurship at the University of Calgary. Check us out here -----> https://linktr.ee/techstartuofc <-----
Or at our website here ---> https://techstartucalgary.com <-----
If you're interested in contributing to this guide or in building similar guides for other areas (like Git, project management, or mobile development), please send me an email at joel.happ1@ucalgary.ca
Good luck on your web dev journey and enjoy the guide!
Part 1 - HTML
HTML is the building block of all webpages. It's ubiquitous throughout application design - everything from websites to mobile apps to desktop apps use HTML as the base for their frontend.
Luckily for you, HTML is also very simple. Don't spend too much time learning it as a beginner - while more advanced HTML concepts do exist, all you need to get started is a basic understanding of how it works.
To get started, I recommend watching this video and experimenting by building your own HTML document alongside it: https://www.youtube.com/watch?v=UB1O30fR-EE
To generate a favicon for your site, use this site: https://realfavicongenerator.net/
No matter which text editor you use (Atom, VSCode, Sublime Text, or something else), I recommend searching for editor plugins to improve your experience writing HTML. Google is your friend here.
Part 2 - CSS
If HTML is the backbone of frontends, CSS is the paint. It's an extremely versatile and powerful way of styling and beautifying your content. CSS is easy to get into, but very difficult to master- if front-end development interests you, I recommend dedicating a significant amount of time towards learning CSS.
To get started, check out this 1 hour introductory video to CSS:
https://www.youtube.com/watch?v=yfoY53QXEnI
Another alternative is this free course on Scrimba, which also covers HTML: https://scrimba.com/learn/htmlcss
One topic that isn't covered in much detail in the previous video is CSS selectors. For most purposes, you'll probably want to keep your selectors simple (using only class names the vast majority of the time). If you want to learn more about advanced selectors, check out this video: https://www.youtube.com/watch?v=Bcr70LIJcOk
When working on projects with other people, I recommend avoiding element-level selectors, as they can easily screw with work that others are doing.
Once you have a good grasp of the basics of CSS, one area that I highly recommend learning is CSS Grid. CSS Grid is a fantastic way of organizing and positioning html content, and it comes with loads of features that make it easy to build adaptive web pages. By combining CSS Grid with CSS breakpoints, you can design interfaces that look great on any size of screen, whether it's a big desktop computer or a small mobile phone.
Highly recommended course for CSS Grid: https://scrimba.com/learn/cssgrid
(Warning: CSS grid is not supported by some outdated browsers and browsers like Opera Mini which are used mostly in third world countries to save data. If your intended audience includes these people, do not use CSS Grid.)
How should you organize and refactor your CSS? I recommend using the BEM strategy for your CSS selectors. https://css-tricks.com/bem-101/
BEM is a particularly helpful methodology to adopt when you're building websites from components like in React, since you can keep the CSS for each component in a separate file. However, it's far from the only strategy for CSS organization, so you can research and adopt others if they suit your needs better.
Knowing CSS Flexbox is also helpful for arranging the layouts of websites. It's like
Finally, here is a great video to watch for some simple, powerful tips for writing modern CSS:
https://www.youtube.com/watch?v=Qhaz36TZG5Y
Part 3 - Javascript
JavaScript drives the interactivity and functionality of websites. Using it, you can respond to the user's interactions on your website and you can modify the properties of your HTML dynamically.
To get started with JavaScript, you can watch this playlist: https://www.youtube.com/playlist?list=PLDyQo7g0_nsX8_gZAB8KD1lL4j4halQBJ
If you're brand new to programming, you should spend more time learning the fundamentals of JavaScript.
There are a few areas of JavaScript which may be confusing to any newcomers to the language, even if you have previously learned other languages. I recommend practicing and studying to get used to these features.
Array functions: https://www.youtube.com/watch?v=rRgD1yVwIvE
Asynchronous JavaScript (Await, Promises, Callbacks): https://www.youtube.com/watch?v=_8gHHBlbziw
JSON (JavaScript object notation): https://www.youtube.com/watch?v=wI1CWzNtE-M
If you encounter another area of JavaScript that gives you troubles let me know and I'll add a section to this guide.
3.1 Node.js
Here's an introduction to Node.js: JavaScript, but for your operating system instead of your browser. https://www.youtube.com/watch?v=ENrzD9HAZK4 Node.js is frequently used as the backend for the server side of an application or web app.
Installing Node.js
We recommend using NVM (node version manager) to install node.js. It allows you to install, uninstall, and switch between different versions of node.js very quickly. Often, you'll need to switch between different versions of node for different projects, so you'll save time by using nvm from the start.
NVM (Mac/Linux): https://github.com/nvm-sh/nvm
NVM for windows: https://github.com/coreybutler/nvm-windows
Once installed, you can type "nvm" in your CLI to see a list of commands you can use. Follow instructions on GitHub for proper usage!
Express
One of the most common Node.js frameworks is Express. Express is an unopinionated (meaning, it doesn't force you to do things any particular way) framework that excels at allowing you to write APIs. We may include more content on Express here in the future.
3.2 TypeScript
TypeScript is a superset of Javascript that introduces new features mostly related to strong typing: this lets you safeguard your variables and functions and helps you catch the most frequent mistakes and bugs from JavaScript code.
TypeScript is contained in .ts files, and using a compiler you can compile it into vanilla JavaScript .js files which run as expected on a computer. If you anticipate doing a lot of work with JavaScript, I highly recommend learning TypeScript - although it isn't necessary for every project, it immensely improves the quality of the coding experience and it can guide you towards mastering tricky concepts from JavaScript like promises and callbacks.
TypeScript tutorial by NetNinja:
https://www.youtube.com/playlist?list=PL4cUxeGkcC9gUgr39Q_yD6v-bSyMwKPUI
TypeScript Basics by JavaBrains: (also includes small project incl. API usage)
https://www.youtube.com/playlist?list=PLqq-6Pq4lTTanfgsbnFzfWUhhAz3tIezU
Part 4 - React
HTML, CSS, and JS are great and all, but what if you want to make a modern, reactive website? Several frontend frameworks exist to empower dynamic, reactive sites, and as of 2021 React is by far the most popular among them. It's a great way to get an introduction into the world of web frameworks and it's a fun tool to use.
Here's a good free overview of the basics of React: https://scrimba.com/learn/learnreact
Plenty of similar courses are available on YouTube and other course platforms.
When in doubt, consult the React documentation: https://reactjs.org/docs/
Note that much of the documentation still uses class-based components, as opposed to function-based components. Nowadays, it is 99% preferable to use function-based components whenever possible. It cuts down on the amount of boilerplate you need to write and enables helpful features from hooks.
Learn more about React Hooks: https://www.youtube.com/watch?v=TNhaISOUy6Q
The 2 hooks in particular you should be very familiar with:
- useState - for basic state/data management
- useEffect - ubiquitous in React. It is used for creating consequences ("effects") for changes in data. It's a critical part of designing React applications to have a functional (not object-oriented) architecture, and you should be using it to create custom hooks.
Other hooks that are handy to know about are useRef, useCallback, and useLayoutEffect.
To learn React, you should know HTML, CSS, and JS before. You can also build React apps with TypeScript instead of JavaScript. https://www.typescriptlang.org/docs/handbook/react.html
React Context API
The context API is a tool you can use in React to share state from an upper level component (a provider) to its children. If you have state that needs to be shared across many children, you can use the context API rather than pass everything down manually as props.
To learn about the context API, I recommend watching this video:
https://www.youtube.com/watch?v=35lXWvCuM8o
React Router
If you want to make React websites with multiple pages, you can use React Router. It is a package that enables your app to have multiple routes. This series gives a quick overview of React Router:
https://www.youtube.com/watch?v=aZGzwEjZrXc&list=PL4cUxeGkcC9gZD-Tvwfod2gaISzfRiP9d&index=21
React Router is lightweight and best suited for very small projects. If you plan on building a larger website with React, we recommend using Next.js instead - it has a lot more features including pre-rendering pages on the server for SEO optimization. Next.js is also widely used and has industry-level support.
React Redux is a commonly used package for managing global state. It allows you to take care of state in a global store that can be accessed or modified from anywhere in your application.
https://www.youtube.com/watch?v=CVpUuw9XSjY
Using React with Typescript
Here is a great cheatsheet that you should read to get started with using React in combination with Typescript:
https://github.com/typescript-cheatsheets/react
That's it! .. for now :)
Happy hacking!
\ No newline at end of file diff --git a/guides/Web_Dev_Guide/images/image1.png b/guides/Web_Dev_Guide/images/image1.png new file mode 100644 index 0000000..3efb287 Binary files /dev/null and b/guides/Web_Dev_Guide/images/image1.png differ diff --git a/guides/Web_Dev_Guide/images/image2.png b/guides/Web_Dev_Guide/images/image2.png new file mode 100644 index 0000000..2793bfa Binary files /dev/null and b/guides/Web_Dev_Guide/images/image2.png differ diff --git a/guides/Web_Dev_Guide/images/image3.png b/guides/Web_Dev_Guide/images/image3.png new file mode 100644 index 0000000..53c2d49 Binary files /dev/null and b/guides/Web_Dev_Guide/images/image3.png differ diff --git a/guides/Web_Dev_Guide/images/image4.png b/guides/Web_Dev_Guide/images/image4.png new file mode 100644 index 0000000..2b86ff9 Binary files /dev/null and b/guides/Web_Dev_Guide/images/image4.png differ diff --git a/guides/Web_Dev_Guide/images/image5.png b/guides/Web_Dev_Guide/images/image5.png new file mode 100644 index 0000000..23087c6 Binary files /dev/null and b/guides/Web_Dev_Guide/images/image5.png differ diff --git a/guides/Web_Dev_Guide/images/image6.png b/guides/Web_Dev_Guide/images/image6.png new file mode 100644 index 0000000..8453ca8 Binary files /dev/null and b/guides/Web_Dev_Guide/images/image6.png differ diff --git a/guides/Web_Dev_Guide/images/image7.png b/guides/Web_Dev_Guide/images/image7.png new file mode 100644 index 0000000..677009d Binary files /dev/null and b/guides/Web_Dev_Guide/images/image7.png differ diff --git a/guides/Web_Dev_Guide/images/image8.png b/guides/Web_Dev_Guide/images/image8.png new file mode 100644 index 0000000..48a0360 Binary files /dev/null and b/guides/Web_Dev_Guide/images/image8.png differ diff --git a/guides/html2Markdown.py b/guides/html2Markdown.py new file mode 100644 index 0000000..b7218d9 --- /dev/null +++ b/guides/html2Markdown.py @@ -0,0 +1,20 @@ + +# import markdownify +import markdownify + + +def get_content(path): + with open(path) as f: + raw = f.read() + return raw + +html = get_content('./Django_Guide/DjangoGuide.html') +print(html) + +# convert html to markdown +h = markdownify.markdownify(html, heading_style="ATX", code_language="python", heading_style_level=2) + +with open('./Django_Guide/DjangoGuide.md', "w", encoding="utf-8") as f: + f.write(h) +f.close() + diff --git a/highlight.css b/highlight.css new file mode 100644 index 0000000..ba57b82 --- /dev/null +++ b/highlight.css @@ -0,0 +1,82 @@ +/* + * An increased contrast highlighting scheme loosely based on the + * "Base16 Atelier Dune Light" theme by Bram de Haan + * (http://atelierbram.github.io/syntax-highlighting/atelier-schemes/dune) + * Original Base16 color scheme by Chris Kempson + * (https://github.com/chriskempson/base16) + */ + +/* Comment */ +.hljs-comment, +.hljs-quote { + color: #575757; +} + +/* Red */ +.hljs-variable, +.hljs-template-variable, +.hljs-attribute, +.hljs-tag, +.hljs-name, +.hljs-regexp, +.hljs-link, +.hljs-name, +.hljs-selector-id, +.hljs-selector-class { + color: #d70025; +} + +/* Orange */ +.hljs-number, +.hljs-meta, +.hljs-built_in, +.hljs-builtin-name, +.hljs-literal, +.hljs-type, +.hljs-params { + color: #b21e00; +} + +/* Green */ +.hljs-string, +.hljs-symbol, +.hljs-bullet { + color: #008200; +} + +/* Blue */ +.hljs-title, +.hljs-section { + color: #0030f2; +} + +/* Purple */ +.hljs-keyword, +.hljs-selector-tag { + color: #9d00ec; +} + +.hljs { + display: block; + overflow-x: auto; + background: #f6f7f6; + color: #000; +} + +.hljs-emphasis { + font-style: italic; +} + +.hljs-strong { + font-weight: bold; +} + +.hljs-addition { + color: #22863a; + background-color: #f0fff4; +} + +.hljs-deletion { + color: #b31d28; + background-color: #ffeef0; +} diff --git a/highlight.js b/highlight.js new file mode 100644 index 0000000..180385b --- /dev/null +++ b/highlight.js @@ -0,0 +1,6 @@ +/* + Highlight.js 10.1.1 (93fd0d73) + License: BSD-3-Clause + Copyright (c) 2006-2020, Ivan Sagalaev +*/ +var hljs=function(){"use strict";function e(n){Object.freeze(n);var t="function"==typeof n;return Object.getOwnPropertyNames(n).forEach((function(r){!Object.hasOwnProperty.call(n,r)||null===n[r]||"object"!=typeof n[r]&&"function"!=typeof n[r]||t&&("caller"===r||"callee"===r||"arguments"===r)||Object.isFrozen(n[r])||e(n[r])})),n}class n{constructor(e){void 0===e.data&&(e.data={}),this.data=e.data}ignoreMatch(){this.ignore=!0}}function t(e){return e.replace(/&/g,"&").replace(//g,">").replace(/"/g,""").replace(/'/g,"'")}function r(e,...n){var t={};for(const n in e)t[n]=e[n];return n.forEach((function(e){for(const n in e)t[n]=e[n]})),t}function a(e){return e.nodeName.toLowerCase()}var i=Object.freeze({__proto__:null,escapeHTML:t,inherit:r,nodeStream:function(e){var n=[];return function e(t,r){for(var i=t.firstChild;i;i=i.nextSibling)3===i.nodeType?r+=i.nodeValue.length:1===i.nodeType&&(n.push({event:"start",offset:r,node:i}),r=e(i,r),a(i).match(/br|hr|img|input/)||n.push({event:"stop",offset:r,node:i}));return r}(e,0),n},mergeStreams:function(e,n,r){var i=0,s="",o=[];function l(){return e.length&&n.length?e[0].offset!==n[0].offset?e[0].offset":e:f.tabReplace?e.replace(/\t/g,f.tabReplace):e):e}function E(e){let n=null;const t=function(e){var n=e.className+" ";n+=e.parentNode?e.parentNode.className:"";const t=f.languageDetectRe.exec(n);if(t){var r=T(t[1]);return r||(console.warn(g.replace("{}",t[1])),console.warn("Falling back to no-highlight mode for this block.",e)),r?t[1]:"no-highlight"}return n.split(/\s+/).find(e=>p(e)||T(e))}(e);if(p(t))return;S("before:highlightBlock",{block:e,language:t}),f.useBR?(n=document.createElement("div")).innerHTML=e.innerHTML.replace(/\n/g,"").replace(/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mark.min.js b/mark.min.js
new file mode 100644
index 0000000..1636231
--- /dev/null
+++ b/mark.min.js
@@ -0,0 +1,7 @@
+/*!***************************************************
+* mark.js v8.11.1
+* https://markjs.io/
+* Copyright (c) 2014–2018, Julian Kühnel
+* Released under the MIT license https://git.io/vwTVl
+*****************************************************/
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):e.Mark=t()}(this,function(){"use strict";var e="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e},t=function(e,t){if(!(e instanceof t))throw new TypeError("Cannot call a class as a function")},n=function(){function e(e,t){for(var n=0;n
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Introduction
+Hi there! +This website contains tutorials, how-to guides, explanations, +and reference documentation of the things we do at +Tech Start UCalgary.
+If you are looking for our main page, +please visit us at techstartucalgary.com.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/projects/demos/1/index.html b/projects/demos/1/index.html
new file mode 100644
index 0000000..34c4226
--- /dev/null
+++ b/projects/demos/1/index.html
@@ -0,0 +1,358 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A good
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Introduction
+Hi there! +This website contains tutorials, how-to guides, explanations, +and reference documentation of the things we do at +Tech Start UCalgary.
+If you are looking for our main page, +please visit us at techstartucalgary.com.
+Motivation
+Guess what most of the top Software Developers have in common?
+They all have cool projects!
+torvalds, +dtolnay, +sindresorhus, +donnemartin, +kamranahmedse, +jwasham, +trekhleb, +tiangolo, +gre, +vmihailenco, +twpayne, +brycedrennan, +marten-seemann, +rusty1s, +kripken, +krisnova.
+And those projects are successful:
+
Tech Start UCalgary mission +is to foster an environment +where people can become a better version of themselves +through creating software projects.
+This website will guide you +through the elements that make a project awesome +while emphasizing industry best practices.
+A good README.md
+A README.md file in the root of the repository
+is going to be the first things your users see.
+GitHub renders this file on the main page of the repository.
This is an example from the NixOS organization:
+
It's important that it's professional and colorful, and that it grabs the user's attention.
+I highly recommend the following elements +are present on the first page:
+-
+
-
+
Logo and name: +A good logo is going to make the project look respected +and professional.
+A good name is able to encapsulate the project's purpose, +or, at the very least, should give the project an identity.
+This is an example from the +Prettier +project:
+
+
It looks good.
+On the other hand, it encapsulates the purpose of the project: +"Making your code prettier".
+
+ -
+
Slogan: +A short, catchy phrase, +summarizing what the project does and its most hot features.
+This is an example from the +FastAPI +project:
++
+FastAPI framework, high performance, easy to learn, fast to code, ready for production.
+Wow. Yes, I want high-performance APIs. +I want things easy to learn, +with no boilerplate, +and robust enough for production.
+While short, +this slogan is very important +because it's displayed on the project card:
+
+
It can be the first thing a new visitor sees +and therefore can be the decisive factor +for a user to click on it.
+It's also displayed on the top of the project home page:
+
+
And sets the expectations for what comes next, +it needs to be good.
+
+ -
+
Description: +Here you will have a few paragraphs to +explain what your project does, +what problem it solves for your users, +and why should a user be using it right now.
+This is an example from the +FastAPI +project:
++
+FastAPI is a modern, fast (high-performance), +web framework for building APIs with Python 3.6+ +based on standard Python type hints.
+The key features are:
+-
+
-
+
Fast: Very high performance, on par with NodeJS and Go (thanks to Starlette and Pydantic). One of the fastest Python frameworks available.
+
+ -
+
Fast to code: Increase the speed to develop features by about 200% to 300%. *
+
+ -
+
Fewer bugs: Reduce about 40% of human (developer) induced errors. *
+
+ -
+
Intuitive: Great editor support. Completion everywhere. Less time debugging.
+
+ -
+
Easy: Designed to be easy to use and learn. Less time reading docs.
+
+ -
+
Short: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs.
+
+ -
+
Robust: Get production-ready code. With automatic interactive documentation.
+
+ -
+
Standards-based: Based on (and fully compatible with) the open standards for APIs: OpenAPI (previously known as Swagger) and JSON Schema.
+
+
* estimation based on tests on an internal development team, building production applications.
+Here the user knows that FastAPI helps build APIs with Python. +They should be using FastAPI right now +because it's fast, intuitive, easy, and so on.
+It's always a good idea to throw a few power-words like: "Fast", "Powerful", "Secure", and "Reliable", +but of course, make sure that this is true.
+You can further improve this section by adding emojis.
+This is an example from the +Alejandra +project:
+
+
To this point, your users should have a clear understanding of:
+-
+
- What problem does your project solve? +
- How does it make the user's life easier? +
- What is special about it? What are the key features? +
But also make sure not to show unnecessary details. +Try to find a balance. +Too short and you'll leave questions unanswered. +Too long and you'll bore or confuse them.
+
+ -
+
-
+
Getting Started: +Users are interested at this point, +they want action now.
+Here we place the shortest path a user can take +to interact with the project. +If there are many, show the fastest/easiest one first, +and then slowly introduce them to the more complex ones.
+This is an example from the +Alejandra +project:
+
+
It simply tells the user to use a web version of the project. +Everybody knows how to click a link, that's easy and nice.
+This is an example from the +Prettier +project:
+
+
Users familiar with Node JS +will find the instructions easy to follow. +However, +some steps could have been removed +and it would have worked the same. +There is no need to overwhelm the user with details at this point. +We can introduce the details later.
+For example, a better version would be:
++
+Install prettier with:
+
+$ npm install --save-dev prettierMake your code beautiful with:
+
+$ npx prettier --write .Remember to keep the first impression simple and intuitive.
+Simplicity is key here.
+
+
Altogether, the following are examples of a good README:
+-
+
-
+
Prettier:
+
+
+ -
+
FastAPI:
+
+
+ -
+
Alejandra:
+
+
+
Lastly, +makeareadme.com also offers some templates and tips.
+You may want to have a look over there.
+A LICENSE.md
+++This is no legal advice.
+
For good or bad, +all of the code that we write +is subject to the following Intellectual Property rights:
+-
+
-
+
Copyright: The right to reproduce, +derivate, +distribute copies, and use the copyrighted work, +and to extend these rights to others.
+
+ -
+
Moral Rights: +The right of being attributed as the author of the work, +and the right to prevent prejudicial distortions of the work (integrity).
+
+
Both concepts can be expanded a little bit more +by reading the following documents +from the U.S. Copyright Office: +1, +2. +It is a very interesting topic.
+For the time being, +think of these rights +as a way for the rights holder +to decide on who and what can be done with the protected work. +Further, without explicit authorization from the rights holder, +you are effectively limited by law from doing anything at all with the work, +unless you can cite Fair Use.
+If you go and read your employee contract, +you'll find that the rights over the work you do for your employer +are "assigned" to the employer +(transferred from you to them), +that you won't exercise your Moral Right of integrity over the work, +and (with luck) +that they'll respect your Moral Right of being attributed, +plus many more clauses that are similar in nature.
+There is also a third concept called +The Public Domain, +which are works to which no Intellectual Property rights apply, +either because they expired, +but usually, because they were expressly waived by the holder.
+
Whether the existence of these rights is good or bad +I leave it for you to think about, +but I'll throw some good articles and books here: +1, +2, +3, +4.
+At Tech Start UCalgary we commit to Open Source everything +under an Open Source Initiative approved license, +but we recommend for source code:
+-
+
- The Unlicense (Public Domain), or +
- The MIT License (Permissive Copyright). +
And for documentation:
+-
+
- CC0 1.0 Universal (Public Domain), or +
- Attribution 4.0 International (Permissive Copyright). +
You can use the following resources to make an informed decision on your project:
+ +We believe the previous licenses are good for the following reasons:
+-
+
- They enable anyone to benefit from the software, +without discrimination, +which aligns well with the club's mission, +and the fact that we are not seeking profit, +but instead, to foster technology. +
- It allows you +or your team, +or anyone in the world, +to continue growing the project +or creating a company out of it in the future. +
Should you not wish to opt-out of the Copyright Monopoly
+by releasing your work into the public domain,
+remember that the rights are yours and not Tech Start UCalgary.
+You haven't signed any Copyright Transfer Agreement
+with us (and you won't)
+so please use Copyright <year> The <project name>'s contributors,
+where the license asks for it.
The projects are yours.
+And in order to ensure future contributions adhere to your license, +make sure to include the following text +somewhere visible in your project, for instance at the end of the README.md:
++++
+- All of the code that you submit to our code repository will be licensed under the
+<license>.- By submitting code to our code repository +you also certify that you agree +to the following Developer Certificate of Origin.
+
This constitutes a very simple +Contributor License Agreement.
+A RoadMap
+A RoadMap is one of the best ways to manifest the future vision of your product +and the strategy and steps +that will be used for achieving that vision.
+A RoadMap is also a great tool to cooperate with other people +because you can prioritize on it the steps +that are yet to be done, +and see who's working on what, +what progress has been made, +and so on.
+This is an example from the Makes project on GitHub:
+
That's a simple RoadMap, yet it has all the important information. +That's nice!
+I highly recommend you create your RoadMap using the Projects feature on GitHub +because it integrates very well with other GitHub features +like Issues, Pull Requests and Milestones, +but it's also fine if you use Jira +or Trello.
+As a rule of thumb, +anything related to making your project awesome +can (and should) go into the RoadMap. +It's also not limited to just programming tasks, +you could perfectly add to the RoadMap +a meeting with your users, +some market research activity, +or having some Pizza with the team.
+A RoadMap is also a living creature, +it evolves as the project evolves +and you can iterate on it on the go. +Don't worry if you don't get it perfectly from the beginning, +but make sure you have one from the beginning!
+How to create a RoadMap?
+Step 1 - Start with Milestones
+My suggestion is that you start by creating a few +Milestones.
+Think about what your project wants to achieve: +Is it maybe a website that allows you to shorten URLs, +like https://tinyurl.com?
+What's the minimum viable product that you can deliver to your users +so that they can start getting a taste?
+You are right! +An ugly webpage, with an ugly textbox and an ugly button, +that when clicked, gives you a beautifully shortened URL :)
+But that's even too far in the future. +What about making your first Milestone +about having an empty webpage? +Your second Milestone could be having a backend that answers a ping request. +Your third Milestone can be designing the database, +such that it stores the shortened URLs; +and your fourth Milestone can be adding the textbox and button to the front-end, +and an endpoint in the back-end that stores and retrieves the shortened URL.
+You see? +we just planned a minimum viable product, +using an agile methodology.
+Congratulations!
+Step 2 - Split the Milestones in smaller Issues
+Now we can proceed to define the individual tasks (GitHub Issues) +that are needed for completing each Milestone, +and most importantly, +we can assign each member of our team an Issue, +and work collaboratively towards the same goal.
+Bonus points if we can plan it so that they can all work in parallel.
+For example, +for Milestone #1 (Having an empty webpage that the user can access), +we could create the following Issues:
+
In words:
+-
+
- Issue #1: Create a Git repository.
+
-
+
- Priority: Medium. +
- Assignee: John. +
+ - Issue #2, after Issue #1: Add a license.
+
-
+
- Priority: High. +
- Assignee: Olivia. +
+ - Issue #3, after Issue #1: Add a README.md.
+
-
+
- Priority: Medium. +
- Assignee: Jane. +
+ - Issue #4, after Issue #1: Initialize an empty React project.
+
-
+
- Priority: Medium. +
- Assignee: Oliver. +
+ - Issue #5, after Issue #4: Use GitHub actions to deploy the front-end into GitHub pages.
+
-
+
- Priority: Medium. +
- Assignee: John. (John should be free, since finishing #4 means #1 was finished). +
+
Boom! Done.
+Now create more Issues for all of the other Milestones.
+Step 3 - Add your Issues to the RoadMap
+My suggestion for this is to keep it simple. +Avoid too many labels, statuses and complexity.
+First, create a Project (a RoadMap) on GitHub. +This is usually under the Projects tab in the organization view:
+
Then define some statuses:
+
-
+
- 🆕 New: Where you place all of the issues initially. +
- 📋 Backlog: The issues that are yet to be done, and their priority. +
- 🏗 In progress: The issues that are being worked on, and who's working on them. +
- ✅ Done: The issues that have been shipped. +
Then, create a priority field:
+
This will help your team focus on the things +that are more impactful to your project.
+You can use the Eisenhower matrix for this:
+-
+
- 🌋 High priority: Issues that are important and urgent. +
- 🏔 Medium priority: Issues that are important, but not urgent. +
- 🏕 Low priority: Issues that are not important, but may be nice to have someday. +
- 🏝 Never priority: Just close the issue :) don't waste your time on this. +
Now you can start adding Issues to your RoadMap:
+
And see what is the progress towards each Milestone, for example:
+
Demos
+At Tech Start UCalgary +all projects are showcased to the world +at the end of each academic year. +In this event, people from different industries and backgrounds +come and give us feedback on the projects, +while also allowing you as a professional and us as a club +to connect and network with different companies.
+This year's showcase is scheduled for April 29th, 2023. +To prepare for the showcase +we want each team to demo their project +on the last dev night of every month until the showcase. +Namely, February 2nd, March 16th, and April 6th, all in 2023.
+Demo #1, February 2nd
+Spirit
+-
+
- Get to know the technical side of your project +a little bit more +and the things you've build so far, +or plan on building. +
- Discovering how we can help you. +
- Help you get out of the way the challenges you see. +
- Monitoring progress is not a goal, +don't feel pressured, +this Demo shouldn't require much preparation, +and instead is more of a sincere conversation. +
Agenda
+We'll go to the table where you are with your team +and talk with you there.
+Driven by the project manager:
+-
+
-
+
Mention your project's name, +the name of its members, +and a short phrase about what your project is about, +and what problem it solves for its consumers.
+
+ -
+
Walk us through your vision:
+-
+
-
+
How do you want your project to look like 3 months for now?
+
+ -
+
Are there any challenges you are facing or may face?
+
+ -
+
What's your number 1 priority as a team right now?
+
+ -
+
What's your number 1 priority as a project manager?
+
+
+ -
+
-
+
Technical overview:
+-
+
- What's your chosen tech stack? +
+
+Note: "Source Code" below means code, diagrams, designs, plots, anything.
+-
+
-
+
Walk us through how a Developer +would clone/access your Source Code +and get started contributing.
+
+ -
+
Walk us through your Source Code.
+
+ -
+
What would be the top 1 thing that if implemented +would make your team contributing experience happier?
+
+
+ -
+
Any closing thoughts?
+
+
May your projects be successful!
+
Demo #2, March 16th
+Spirit
+-
+
- Get to know the technical side of your project +a little bit more +and the things you've build so far, +or plan on building. +
- Discovering how we can help you. +
- Help you get out of the way the challenges you see. +
- Monitoring progress is not a goal, +don't feel pressured, +this Demo shouldn't require much preparation, +and instead is more of a sincere conversation. +
Agenda
+We'll go to the table where you are with your team +and talk with you there.
+Driven by the project manager:
+-
+
-
+
Elevator Pitch (30 - 60 seconds)
++
+Goal: keep it short, sweet, and memoriable.
+-
+
- Introduce your project's name and members. +
- Discuss the problem you are attempting to solve +
- What is your solution? +
- How does your solution specifically addresses the problem. +
+ -
+
Progress and Challenges faced since Demo #1:
+-
+
- Recap: What's your chosen tech stack (code, diagrams, designs, plots, ect)? +
- Overall, what has been worked on since Demo #1? +
- What are 3 main sucesses the team is proud of since Demo #1? +
- What are some major challenges that were encountered? How did you overcome them? +
+ -
+
Roadmap for the Final Showcase:
+-
+
- What do you hope to achieve by the Final Showcase on April 29th, 2023? +
- Where do you sit on your timeline for progression for the above goal? +
- Are there any challenges you are currently facing or may face? +
- What resource(s) would be useful to help the team achieve the goal? For example, aid in understanding how to deploy in AWS or the app store from creditable and effective online resources or an industry professional. +
+ -
+
Any closing thoughts?
+
+
May your projects be successful!
+
Demo #3, April 6th
+Spirit
+-
+
-
+
Do a final showcase simulation.
+
+ -
+
Show the world what you've built.
+
+ -
+
See what other teams have built.
+
+ -
+
No matter what, enjoy the process.
+The amount of hard work, dedication, +and teamwork required to bring an idea to life is immense, +and you should all feel incredibly proud +of what you have accomplished in the last two seasons. +You have overcome countless obstacles and challenges, +honed your skills, and become a better version of yourself. +Now, as you stand at the finish line +and look back on what you have achieved, +take a moment to appreciate how far you have come +and how much you have grown. +Your project is a testament to your passion, creativity, and perseverance, +and it serves as a reminder that with the right mindset and determination, +anything is possible.
+
+
Agenda
+The content is up to you! +The way you deliver your presentation matters, +so feel free to drop here your signature style.
+Just remember that in the final showcase +(and therefore in this demo), +you'll have:
+-
+
-
+
Maximum 15 minutes for your presentation.
+
+ -
+
Maximum 3 minutes for questions and answers.
+
+ -
+
Most of the audience will be completely new to your project.
+
+ -
+
Teams will present in the following order:
+-
+
- Bandist. +
- CyberHire. +
- EasyMeal. +
- LifeLine. +
- AiRM. +
- TechstArcade. +
+ -
+
The judges will score based on +this rubric, +so if you want to win some prizes you may want to optimize for that.
+
+ -
+
Please prepare your responses for the following retrospective questions:
+-
+
- What was the most challenging aspect of the project and how did you overcome it? +
- Looking back, what would you have done differently in terms of planning or execution? +
- How did each team member contribute to the project, and what strengths did they bring to the team? +
- What did you learn from working on this project that you can apply to future projects? +
- In what ways did the project meet or exceed your initial expectations, and why? +
- Did you feel that the project had a meaningful impact, either for your team or for others? +
- What is your plan for the next 3 weeks leading up to the final showcase? +
+
Lastly, just remember to look back on what you have achieved, +and take a moment to appreciate how far you have come +and how much you have grown.
+We all feel very proud of you and believe in you.
+Career Paths
+There are several areas of software development that cover different aspects of the software development life cycle. +Usually, people focus on only one or a couple of them. Each of them is a big area on its own and takes years to learn:
+-
+
-
+
Front-end development: This area of software development is concerned with the user interface (UI) and user experience (UX) of software applications. Front-end developers work with technologies like HTML, CSS, and JavaScript to create the visual elements that users interact with.
+
+ -
+
Back-end development: This area of software development is concerned with the server-side of software applications. Back-end developers work with technologies like PHP, Python, Ruby, and Java to create the logic that powers software applications.
+
+ -
+
Full-stack development: Full-stack developers work on both the front-end and back-end of software applications. They have knowledge and skills in both areas of development and can build complete applications from start to finish.
+
+ -
+
Mobile development: This area of software development is concerned with creating applications for mobile devices. Mobile developers work with technologies like Java, Swift, and Kotlin to create native apps for iOS and Android devices.
+
+ -
+
DevOps: DevOps is a methodology that focuses on collaboration between development and operations teams to automate the software delivery process. DevOps engineers use tools like Jenkins, Ansible, and Docker to automate the software development process.
+
+ -
+
Testing and quality assurance: This area of software development is concerned with ensuring that software applications are reliable, bug-free, and meet the requirements of the end-users. Testing and quality assurance engineers use tools like Selenium, JMeter, and LoadRunner to test software applications.
+
+ -
+
Data science and analytics: This area of software development is concerned with creating applications that analyze and interpret data. Data science and analytics engineers work with technologies like Python, R, and SQL to build applications that can perform data analysis, machine learning, and statistical modeling.
+
+ -
+
Artificial intelligence and machine learning: This area of software development is concerned with creating applications that can learn and make decisions based on data. AI and ML developers work with technologies like Python, TensorFlow, and PyTorch to build applications that can perform tasks like natural language processing, image recognition, and predictive modeling.
+
+ -
+
Cybersecurity: This area of software development is concerned with creating secure software applications and protecting them from malicious attacks. Cybersecurity engineers work with technologies like encryption, firewalls, and intrusion detection systems to secure software applications.
+
+ -
+
Cloud computing: This area of software development is concerned with creating applications that can run on cloud computing platforms like Amazon Web Services, Microsoft Azure, and Google Cloud Platform. Cloud developers work with technologies like containerization, serverless computing, and cloud storage to build and deploy applications on the cloud.
+
+ -
+
Embedded systems: This area of software development is concerned with creating software for embedded devices like medical devices, smart appliances, and automotive systems. Embedded systems developers work with technologies like C, C++, and assembly language to create software that runs on these devices.
+
+ -
+
Augmented and virtual reality: This area of software development is concerned with creating applications that allow users to interact with virtual or augmented environments. AR and VR developers work with technologies like Unity, Unreal Engine, and WebXR to build immersive applications for gaming, education, and training.
+
+ -
+
Project management: Involves overseeing the entire software development process from conception to delivery. Project managers are responsible for ensuring that the project is completed on time, within budget, and to the required quality standards.
+
+ -
+
Product owner: The product owner is responsible for defining and prioritizing the features and requirements of a software application. They work closely with development teams, stakeholders, and customers to ensure that the product meets the needs of the users.
+
+ -
+
Technical writing: Technical writers create documentation and user manuals for software applications. They work with developers and other technical experts to create user-friendly documentation that explains how to use the software application.
+
+ -
+
User experience (UX) design: UX designers create the visual design and user experience of software applications. They work with developers to ensure that the application is easy to use and visually appealing.
+
+ -
+
Technical support: Technical support engineers provide support to users who are experiencing issues with software applications. They work with developers to diagnose and resolve technical issues, and provide customer support to users.
+
+ -
+
Technical architecture: Technical architects are responsible for designing the technical architecture of software applications. They work with development teams to ensure that the architecture meets the scalability, security, and performance requirements of the application.
+
+ -
+
Database administration: Database administrators are responsible for managing the data that is used by software applications. They work with developers to design and implement databases, and ensure that the data is stored and managed effectively.
+
+
Front End
+A front-end engineer is a software engineer who specializes in building the user interface (UI) and user experience (UX) of a website or application. They are responsible for creating visually appealing and intuitive designs that allow users to interact with the application or website seamlessly.
+The front-end engineer's job involves using various technologies such as HTML, CSS, and JavaScript to build the visual elements of an application or website. They work closely with designers to turn mockups and wireframes into fully functional websites or applications that are easy to use and navigate.
+Front-end engineers also collaborate with back-end engineers to integrate the front-end code with the back-end code, ensuring that the entire system functions correctly. They are responsible for testing and debugging the front-end code, optimizing the code for performance, and ensuring that the website or application is compatible with different browsers and devices.
+How to become a front-end engineer?
+To become a front-end engineer, you will need to follow these general steps:
+-
+
-
+
Learn HTML, CSS, and JavaScript (or TypeScript): HTML is used to structure web pages, CSS is used to style them, and JavaScript is used to add interactivity and dynamic behavior. These are the core technologies used in front-end development.
+
+ -
+
Learn a front-end framework: While it's not strictly necessary, learning a front-end framework like React can help you to build more complex web applications more efficiently.
+
+ -
+
Build projects: To gain practical experience, you should work on building your own projects or contributing to open-source projects. This will help you to develop your skills and build a portfolio of work that you can show to potential employers.
+
+ -
+
Stay up-to-date: Front-end development is a rapidly evolving field, so it's important to stay up-to-date with the latest technologies and best practices. Attend conferences, read blogs and forums, and participate in online communities to stay current.
+
+ -
+
Apply for jobs: Once you have the skills and experience, it's time to start applying for front-end engineering jobs. Look for job postings online, reach out to recruiters or companies directly, and attend networking events to make connections in the industry. Be prepared to showcase your portfolio and be able to talk about your skills and experience during interviews.
+
+
DevOps
+DevOps is a software development approach that emphasizes collaboration and communication between software developers and IT operations professionals. The goal of DevOps is to improve the efficiency and quality of software development by breaking down silos and promoting a culture of collaboration, automation, and continuous improvement.
+Traditionally (https://clickup.com/blog/waterfall-project-management/), software development and IT operations have been two separate functions within organizations, with little interaction between them. DevOps seeks to bridge this gap by fostering collaboration between these teams throughout the entire software development lifecycle, from planning and development to deployment and maintenance.
+DevOps involves using tools and practices such as continuous integration, continuous delivery, and infrastructure automation to streamline the software development process and make it more efficient. By automating tasks like testing, building, and deploying software, teams can reduce errors, speed up the development process, and deliver software more quickly and reliably.
+Overall, DevOps is a holistic approach to software development that aims to create a culture of collaboration and continuous improvement, with the goal of delivering software more efficiently and with higher quality.
+How to become a DevOps engineer?
+-
+
-
+
Understand the why and the high-level how (the philosophy).
+For instance:
+-
+
- Get to know The Three Ways: https://itrevolution.com/articles/the-three-ways-principles-underpinning-devops/. +
- Read a book: https://www.amazon.com/DevOps-Handbook-Second-World-Class-Organizations/dp/B09L56CT6N. +
- Win in this game: +https://devops.games/. +
+ -
+
Learn the core skills: DevOps engineers need a strong foundation in software development, You should have a basic understanding of programming languages, and be familiar with version control systems like Git. You should also have experience working with Linux/Unix systems and be familiar with cloud platforms like AWS, Azure, or Google Cloud Platform.
+
+ -
+
Gain experience with DevOps tools and practices: DevOps engineers should be familiar with tools and practices such as continuous integration/continuous delivery (CI/CD), infrastructure as code, configuration management, and monitoring and logging. You can gain experience by working on projects, contributing to open-source projects, or taking online courses.
+
+ -
+
Learn automation: Automation is a key part of DevOps, so you should have experience with containerization tools like Docker and Kubernetes.
+
+ -
+
Build projects: To gain practical experience, you should work on building your own projects or contributing to open-source projects. This will help you to develop your skills and build a portfolio of work that you can show to potential employers.
+
+ -
+
Stay up-to-date: DevOps is a rapidly evolving field, so it's important to stay up-to-date with the latest tools and practices. Attend conferences, read blogs and forums, and participate in online communities to stay current.
+
+ -
+
Apply for jobs: Once you have the skills and experience, it's time to start applying for DevOps engineering jobs. Look for job postings online, reach out to recruiters or companies directly, and attend networking events to make connections in the industry. Be prepared to showcase your portfolio and be able to talk about your skills and experience during interviews.
+
+
Dealing With Conflict
+Conflict resolution is the process of resolving differences +and disputes between individuals, groups, +or parties through peaceful means. +It involves identifying and addressing the underlying causes of the conflict, +promoting communication and understanding, cooperation, +and finding a mutually acceptable solution, +leading to increased productivity +and satisfaction in personal and professional settings. +When done correctly, +it helps to manage and resolve differences and disputes effectively, +preventing them from escalating into larger and more destructive problems.
+The following document enumerates the trade-offs +of all conflict management styles, +and I highly encourage you to read it.
+https://www.valamis.com/hub/conflict-management-styles.
+Lastly, remember that conflict is not a bad thing. +Instead, learn how to manage it and make the most out of it.
+++"If you want to go fast, go alone; if you want to go far, go together."
+
CSS
+Is only recommended to learn CSS after you are familiar with HTML.
+Fundamentals
+MDN is all you'll need. +Read it from beginning to end: +https://developer.mozilla.org/en-US/docs/Web/CSS.
+Particularly, focus on:
+-
+
- The basic syntax, common attributes (color, font, border) +and basic selectors. +
- The Box Model. +
- CSS Layouts +(Flexbox and Grids as a minimum). +
- Responsive Design and media queries. +
Related utilities:
+-
+
- https://css-tricks.com/snippets/css/a-guide-to-flexbox/ +
- https://css-tricks.com/snippets/css/complete-guide-grid/ +
Popular libraries
+Learn only after you learn the fundamentals:
+ +Advanced
+When you want to architect a big scope system:
+ +Be aware of
+But not necessarily learn them:
+ +HTML
+Fundamentals
+MDN is all you'll need. +Read it from beginning to end: +https://developer.mozilla.org/en-US/docs/Learn/HTML.
+You should focus on the basics only (a, button, h1-h6, p, span, lists, div, input, ...).
+HTML is not more complicated than that, learn about CSS next.
+Management Styles
+++A management style is the way +in which a manager works to fulfill their goals. +Management style includes the way that a manager plans, organizes, makes decisions, delegates, +and manages their staff.
+
All management styles are useful depending on the specific scenario, +but it's important to identify when to use which one, +since a wrong management style conduces the team to a dissatisfied, unengaged, inefficient, unmotivated, or frustrated state.
+The following document enumerates the trade-offs +of all management styles and I highly encourage you to read it.
+https://www.valamis.com/hub/management-styles.
+I would just add a last tip here:
+Understand what motivates every person on your team.
+For instance, +remember that a team of volunteers is very different from a team of employees. +On a volunteering team, the motivation factors usually are +self-development and being part of a cause. +The key in this setup +is aligning the team's objectives +with each person's definition of meaningfulness.
+Secrets Management
+In this Workshop, we'll learn how to properly store the secrets +that your application's source code needs to run +like database connection strings and third-party API access credentials, +and do so even if people have access to your source code.
+We'll be exploring three approaches used in industry, +and talking about when to use one or the other:
+-
+
- Git Crypt. +
- SOPS - My favorite. +
- Hashicorp's Vault. +
We'll also talk a little bit about the Twelve-Factor app, +particularly about factor #3: Configuration.
+Pre-requisites
+To be able to focus on the important aspects of this Workshop (secrets management) +and avoid distractions we'll assume you are familiar with Git +and the command line.
+Please bring your laptop, +the idea is that we'll work together step by step on small exercises +that will teach you each of the tools.
+Only MacOS and Linux are supported. +If you are on Windows, +please install WSL.
+Please come to the workshop with the following tools ready to be used:
+-
+
-
+
A terminal where you can enter commands, set environment variables, etc.
+
+ -
+
Git.
+
+ -
+
Git Crypt:
+Run
+$ brew install git-crypton MacOS, +or$ apt install git-cryptor similar on Linux/WSL.
+ -
+
Sops:
+Run
+$ brew install sopson MacOS, +or$ apt install sopsor similar on Linux/WSL.
+ -
+
Age:
+Run
+$ brew install ageon MacOS, +or$ apt install ageor similar on Linux/WSL.
+ -
+
Vault:
+Please follow the instructions here: +https://developer.hashicorp.com/vault/downloads.
+
+
Why?
+Application secrets are critical for security. +For example, if an attacker discovers the database credentials, +then immediately this attacker would gain access to all of the applications data. +Application secrets is the entrypoint for everything, they are the Keys of Heaven, +and therefore, it's very important to make sure +that only the right people can get access to those secrets.
+In this line of making application secrets be only accessible to the right people +we also need to make sure that developers can only access development secrets. +It's very common to have at least 2 environments: Development and Production, +and to have some kind of segmentation where only super admins can access Production secrets.
+It also doesn't matter if your source code is private, +you still want to protect your secrets because your source code may be leaked, +as it has happened in the past to companies like Twitch.
+There is also an argument about maintainability. +Secrets are also configuration, namely, their values may change over time, +even if the source code doesn't. For this reason it's recommended to +strictly separate them from the source code.
+Workshop Step by Step
+Git-Crypt
+++https://github.com/AGWA/git-crypt
+
Enables you to encrypt/decrypt the parts of a git of repository.
+The good:
+-
+
- Versioned as code. +
- It's simple to use. +
- Great for a simple project, with no compliance needs. +
The bad:
+-
+
- You cannot have multiple keys. All people share the same encryption key, +which means you cannot isolate environments, +and therefore is not that useful in highly regulated industries. +
- Unencrypted secrets touch the disk, +which is not great if someone steals your laptop while unencrypted. +
Steps:
+-
+
-
+
+
As you can see, there are
+devandprodsecrets withusernameandpassword, but they are encrypted, so we cannot see them unless we have they key.
+ -
+
Download the key here
+Note: This should be distributed through a secure channel (e.g. encrypted email). +For the sake of simplicity you can download it here.
+
+ -
+
Now we want to decrypt the secrets, for this we have to:
+
+$ git clone https://github.com/techstartucalgary/Docs.git docs +$ cd docs + +docs $ cat src/workshops/secrets-management/git-crypt/secrets/dev/username + <you should see gibberish> + +# Decrypt +docs $ git-crypt unlock /path/to/key + +# You should see the secrets now +docs $ cat src/workshops/secrets-management/git-crypt/secrets/dev/username +docs $ cat src/workshops/secrets-management/git-crypt/secrets/dev/password + +# Encrypt +docs $ git-crypt lock +docs $ cat src/workshops/secrets-management/git-crypt/secrets/dev/username + <you should see gibberish again> +
+ -
+
The next step is understanding how it works, so essentially you configure which paths of the repository are encrypted in a
+.gitattributesfile like this one: +https://github.com/techstartucalgary/Docs/blob/main/src/workshops/secrets-management/git-crypt/.gitattributes, +where essentially we tell git-crypt to encrypt the files under the secrets/ folder. You can check which files are encrypted with
+$ git-crypt status + not encrypted: src/workshops/secrets-management/README.md + encrypted: src/workshops/secrets-management/git-crypt/secrets/dev/password + encrypted: src/workshops/secrets-management/git-crypt/secrets/dev/username + encrypted: src/workshops/secrets-management/git-crypt/secrets/prod/password + encrypted: src/workshops/secrets-management/git-crypt/secrets/prod/username + not encrypted: src/workshops/secrets-management/git-crypt/unsafe/key +
+
Sops
+++https://github.com/mozilla/sops
+
Enables you to encrypt/decrypt JSON, YAML, or whole files.
+The good:
+-
+
- Versioned as code. +
- You can have multiple keys and access control over a whole file, +great for highly regulated industries. +
- Keys can be connected to an AWS/GCP/Azure identity, +which is great in corporate environments, +and Age/PGP, which is great for other environments. +
The neutral:
+-
+
- Not that easy to use, but reasonable given the features. +
The bad:
+-
+
- Requires some training to get used to it. +
Steps:
+-
+
-
+
Visit https://github.com/techstartucalgary/Docs/tree/main/src/workshops/secrets-management/sops.
+As you can see, there are
+devandprodsecrets withusernameandpassword, but they are encrypted, so we cannot see them unless we have they key.
+ -
+
Download the development key +here +and the production key +here
+Note: This should be distributed through a secure channel (e.g. encrypted email). +For the sake of simplicity you can download it here.
+
+ -
+
Now we want to decrypt the secrets, for this we have to:
+
+$ git clone https://github.com/techstartucalgary/Docs.git docs +$ cd docs + +$ cd src/workshops/secrets-management/sops + +src/workshops/secrets-management/sops $ cat dev.yaml + <you should see gibberish> + +src/workshops/secrets-management/sops $ cat prod.yaml + <you should see gibberish> + +# Decrypt dev secrets with dev key +src/workshops/secrets-management/sops $ SOPS_AGE_KEY_FILE=/path/to/dev/key sops -d dev.yaml + +# Decrypt prod secrets with dev key +src/workshops/secrets-management/sops $ SOPS_AGE_KEY_FILE=/path/to/dev/key sops -d prod.yaml + <you should see a failure, wrong key> + +# Decrypt prod secrets with prod key +src/workshops/secrets-management/sops $ SOPS_AGE_KEY_FILE=/path/to/prod/key sops -d prod.yaml +
+
Vault
++ ++
The good:
+-
+
- Big enterprises like it. Why? Maybe marketing? I assume is because it allows for centralization, which is important if you have hundreds of teams. +
The neutral:
+-
+
- Very flexible. +
The bad:
+-
+
- Another server to maintain. +
- Not versioned as code. +
- Not free. +
++Note: https://vault.kamadorueda.com will be only available during the workshop. If you are following this guide after the workshop, please use your own Vault instance instead.
+
Steps:
+-
+
-
+
Login to the UI at https://vault.kamadorueda.com/ui. The token is
+123.
+ -
+
Let's put and get a secret out of it
+
+$ export VAULT_ADDR=https://vault.kamadorueda.com + +# Login. The token is: 123 +$ vault login + +$ vault kv put secret/your-name password=your-password + +$ vault kv get -field=password secret/your-name +
+ -
+
It's possible to define access control lists, policies, and grant each person a different token, or login with OIDC. It's very flexible.
+
+
Tech Start's Django Guide
+Django is a free and open source python framework that lets you build awesome backends for websites, apps, and more. You can use it to host databases and build secure APIs for them without writing a line of SQL. You can also use it to create multi-page applications with dynamically served content. It makes it easy to get started building complex functionalities by automating a lot of the boilerplate code that you'd normally have to write.
+We recommend that you have a basic knowledge of python before using django! This will help you debug any errors that you get.
+
(Img src: https://medium.com/crowdbotics/when-to-use-django-and-when-not-to-9f62f55f693b)
++
Setup
+Before you get started with Django, you should set up your environment. You should have a recent version of Python installed. You can follow the directions here:
+https://docs.djangoproject.com/en/3.1/howto/windows/
+You should make a venv for your django project.
+
Video tutorial for venv windows: https://www.youtube.com/watch?v=APOPm01BVrk
+Video tutorial for venv mac/linux: https://www.youtube.com/watch?v=Kg1Yvry_Ydk
+Note: if you're using Git Bash on windows, use **$ source venv/scripts/activate
When you're done using your virtual environment, just enter **$ deactivate
https://docs.djangoproject.com/en/3.1/intro/tutorial01/
+ $ python -m pip install Django
+Get Django installed once you have created your virtual environment.
+ $ python -m django --version
+// Checks if you have django installed
+Next, cd into the folder which you want to contain your project and run the following command:
+ $ django-admin startproject pNameHere
+// starts project. cd into pNameHere folder.
+Good to know: Projects vs. apps
+What's the difference between a django project and a django app? An app is a Web application that does something – e.g., a Weblog system, a database of public records or a small poll app. A project is a collection of configuration and apps for a particular website. A project can contain multiple apps. An app can be in multiple projects.
+ $ python manage.py startapp yourAppName
+This creates an app within your project. You'll need to be in the same folder that holds your project's manage.py
+Next step: include your app in the INSTALLED_APPS fields in settings.py (just the name)
+INSTALLED_APPS = [
+ 'django.contrib.admin',
+ 'django.contrib.auth',
+ 'django.contrib.contenttypes',
+ 'django.contrib.sessions',
+ 'django.contrib.messages',
+ 'django.contrib.staticfiles',
+
+ #Add your app name like this!
+ 'myAppName',
+]
+Writing Models
+Models allow you to define the content of your database. If you don't need content in your database, you won't need models.
+You can follow along with this section here:
+https://docs.djangoproject.com/en/3.1/intro/tutorial02/
+More about models: https://docs.djangoproject.com/en/3.1/topics/db/models/
+You will define all your models in models.py, located within the folder for your app.
+from django.db import models
+
+# Create your models here.
+class Album(models.Model):
+ name = models.CharField(max_length=200)
+ artist = models.CharField(max_length=100)
+ year_released = models.DateField()
+ def __str__(self):
+ return str(self.name)
+
+class Song(models.Model):
+ song_name = models.CharField(max_length=100)
+ album = models.ForeignKey(Album, on_delete=models.CASCADE)
+ num_streams = models.IntegerField()
+ def __str__(self):
+ return str(self.song_name)
+Each model should correspond to the structure of a table of a relational model of a database. If you don't know what this means, ask someone who has taken CPSC 471 (or an equivalent databases course)
+Django can convert these into real SQL tables!
+-
+
- Good to know: Primary Keys: In the above example we didn't specify any ids for our models (normally, with databases, you want an id to be your primary key). Django automatically creates an ID field to be the primary key for each model and takes care of auto-incrementing, unless you specifically override it. I don't recommend overriding, it's not worth the effort (and its doubly complicated and not worth it to have a primary key composed of several fields) +
- Good to know: str: the str function is Python's default function for string representation. In this case, it's good practice to override this for your models. This will help you understand your data if you login via the admin view (I'll show how to do this later) +
- Good to know: Foreign Keys: See the Song model class for how you can reference a foreign key belonging to another model (in this case it refers to Album). You don't need to refer to a foreign model's keys directly, all you need to do is specify which table you are referencing. Also note: if you are referring to a table, it needs to be defined above the point in the code where you are referring to it. +
There are more options that can be explored about how you can define your models, but this should be a good base for you to do your own research :)
+Now we're ready to convert these into a real database! By default, Django will make a sqlite file that has your database.
+Converting models into your database
+
+https://docs.djangoproject.com/en/3.1/intro/tutorial02/
+
+>> python manage.py makemigrations appName
+Creates migrations for the changes you made in appName
+
+>> python manage.py migrate
+Migrates the changes you made into your database
+
+Run your app
+Whenever you are ready to run your server, just call this command!
+>> python manage.py runserver
+By default, this will run the Django server on localhost:8000. View the django documentation to see how you can run it on a different port. You can now access it from your web browser by visiting http://localhost:8000 !
+You can also create a superuser (admin) to view the inner contents of your database. To do this, you first need to create them from the command line using the following command:
+>> python manage.py createsuperuser --username yourNameHere --email yours@email.ca
+This will create a super user with your provided info (it will prompt you to enter a password as well).
+The following command creates a token for the superuser that you can use for authentication in requests. If you are not using Django Rest Framework, this is not applicable to you.
+>> python manage.py drf_create_token yourSuperUserName
+Note: if you're trying to run these for your deployed app on heroku, you need to prepend heroku run before those commands! See the Heroku section for a description on how you can deploy it.
You can see the admin page of your website to view the inner content of your database. This is automatically created by Django. Visit http://localhost:8000/admin and enter your passcode.
+If you want your models to show up in the admin page, you will need to specify them in admin.py like this:
+from django.contrib import admin
+from .models import Album, Song
+# Register your models here.
+
+admin.site.register(Album)
+admin.site.register(Song)
+Once you log in to the admin site, you should see something like this. From here, you can add & remove database entries.
+
URLs
+URLs allow you to define the paths that exist in your system, and what happens when you call them.
+URLs documentation: https://docs.djangoproject.com/en/3.1/ref/urls/
+How URLs are processed in Django: https://docs.djangoproject.com/en/3.1/topics/http/urls/#how-django-processes-a-request
+Read more: https://docs.djangoproject.com/en/3.1/intro/tutorial03/
+If you're constructing a big application, it's standard practice in django to include different _apps _for each part of your system, and link them to the main project.
+
However, since we're only making small-scale side-projects, it's fine to ignore this best-practice and include everything in a single app. Just understand that in a large industrial scale project you wouldn't necessarily want to do this.
+// urls.py in a project:
+from django.contrib import admin
+from django.urls import path, include
+
+urlpatterns = [
+ path('admin/', admin.site.urls),
+ path('myApp/', include('myApp.urls'))
+]
+// example urls.py in myApp folder:
+from django.urls import path
+from . import views
+
+urlpatterns = [
+ path('hello_world', views.ping, name='Hello World!'),
+ path('hello-x/<str:hello_to>', views.hellox, name='Hello to x'),
+ path('hello-x/<print_me>/print', views.printx, name='Print this!'),
+ path('goodbye', views.goodbye, name='goodbye'),
+]
+Now you can visit a path using http://localhost:8000/myApp/hello-world, for example.
+Views
+**Views **allow you to define what happens when you access a certain url in your system (using your browser, an API tool like Postman, or something else altogether). In your views, you could define interactions with the model (your database) or entirely different interactions altogether. You can use the definition of the view to call external processes.
+If you want to make more complicated views and understand the Request and Response items, read this:
+https://docs.djangoproject.com/en/3.1/ref/request-response/
+To understand views more in-depth, read the documentation: https://docs.djangoproject.com/en/3.1/topics/http/views/
+Here are some simple examples of what you can do with a view. Note that these are just examples and don't represent best practice at all.
+from django.http import HttpResponse, response
+# views.py
+def ping(request):
+ myRes = "Hello World!"
+ return HttpResponse(myRes)
+
+def hellox(request, hello_to):
+ myRes = {"My Reply": "Hello " + hello_to}
+ return response.JsonResponse(myRes)
+
+def printx(request, print_me):
+ print("Hello to " + print_me)
+ return response.HttpResponseNotFound("I printed it!")
+
+def goodbye(request):
+ if not (request.method == 'GET'):
+ return response.HttpResponseBadRequest()
+ queryParams = request.GET
+ msg = queryParams.get('msg', "Gamers")
+ return response.JsonResponse({"Reply": "Goodbye " + msg})
+Now, we want to adhere to DRY (Don't repeat yourself) when creating views. Therefore, it is almost always best to define your views as Class-Based views (CBVs) which handle more of the boiler plate code for you and help ensure your views follow standards.
+Please read more about class-based views here: https://docs.djangoproject.com/en/3.1/topics/class-based-views/
+Both the above docs and the docs for views also show how you can interact with your database items through a view. But, if you're building an API, I highly recommend using the tools in the following section: Django REST Framework.
+Once you have defined your views and given them a corresponding url, you can test them out.
+>> python manage.py runserver
+Run your server, and using either a web browser, or preferably an API testing tool like Postman (https://www.postman.com/) access the proper urls (ex. http://localhost:8000/myApp/hello_world) to see if they have the expected behavior.
++
Django REST Framework
+Django REST Framework is an add-on to Django that makes it simple to develop REST-compliant APIs. There is great documentation here: https://www.django-rest-framework.org/ <--- FOLLOW INSTALL INSTRUCTIONS
+What is a RESTful framework? Learn more here: https://restfulapi.net/
+Django REST Framework provides you with tools to make class-based views to easily implement database CRUD (Create Read Update Destroy) operations, as well as define more complex operations.
+Before we define any endpoints with Django REST Framework, let's make some serializers.
+
Serializers
+Django REST Framework uses serializers as a way to perform **translation **of your models from your python code and your database into data formats like JSON and XML that an API might use. Read more about them here:
+https://www.django-rest-framework.org/api-guide/serializers/
+We should define some basic serializers so that we can make API endpoints that interact with the content of our database models.
+-
+
- Create a new file called serializers.py inside the app you want to use serializers with. +
- Create your serializers. Give them a relevant name (though the exact syntax is not important) +
- List the fields that you want your serializer to translate. If you don't want it to translate a particular field, then don't include it. +
Here's an example, using the Song and Album models we defined earlier. Here's what's at the top of serializers.py:
+from rest_framework import serializers
+from .models import *
+
+class SongSerializer(serializers.ModelSerializer):
+ class Meta:
+ model = Song
+ fields = ("id", "song_name", "num_streams")
+
+class AlbumSerializer(serializers.ModelSerializer):
+ class Meta:
+ model = Album
+ fields = ("name", "year_released", "artist", "id")
+Make sure your fields match exactly the names that you used in your models.
+You may be curious why I also included an id, when we didn't define one in our models- this is because Django auto generated an id for us in this models because we didn't specify a primary key. This id field always has the name id. It is often useful for our API, so we'll include it.
+We can also create multiple serializers for the same models, if we wanted different behavior. For example, what if we wanted to include the album id of the song?
+class SongSerializerWithAlbumId(serializers.ModelSerializer):
+ class Meta:
+ model = Song
+ fields = ("id", "song_name", "num_streams", "album")
+This would include the album's PK (in this case, it's id, but if the PK was different, it'd be something else).
+What if we wanted to include the full album info when an api request was made to see the song? Here's another example serializer that we could make:
+class SongSerializerFullAlbum(serializers.ModelSerializer):
+ myFullAlbumDesc = AlbumSerializer("album", read_only=True)
+ class Meta:
+ model = Song
+ fields = ("id", "song_name", "num_streams", "myFullAlbumDesc")
+It's using our album serializer from earlier to serialize a field, which must (read only is an optional parameter that makes it so that it's only included in reading requests, not create/update/destroy.)
+This was just an introduction to serializers. If you want to use more complex behaviors, you'll have to do the research on your own.
+Django REST Framework: Class based Views
+Pre-requisite to this section: understand URLS and views in vanilla Django, and read the serializers section
+More reading: https://www.django-rest-framework.org/tutorial/3-class-based-views/
+Video overview of similar topic: https://www.youtube.com/watch?v=akvFA5VMXJU
+You can use Django's Class Based Views to quickly create views that can do CRUD (Create, Read, Update, Destroy) operations on your database.
+In views.py:
+from rest_framework.views import APIView
+from rest_framework import generics
+from rest_framework import status
+from .models import *
+from .serializers import *
+Some class based views that we'll define. Right now these are just the generic create, read, update, destroy views. By defining these views with the classes, Django REST Framework takes care of the default behavior for us. It's that easy!
+class SaveSong(generics.CreateAPIView):
+ queryset = Song.objects.all()
+ serializer_class = SongSerializerWithAlbumId
+
+class GetSongs(generics.ListAPIView):
+ queryset = Song.objects.all()
+ serializer_class = SongSerializer
+
+class DeleteSong(generics.DestroyAPIView):
+ queryset = Song.objects.all()
+ serializer_class = SongSerializer
+
+class UpdateSong(generics.RetrieveUpdateAPIView):
+ queryset = Song.objects.all()
+ serializer_class = SongSerializerWithAlbumId
+Notice that we need to make the create and update serializers include the album ID- if we didn't then you couldn't create song objects since their album id must be _not null._This same principal applies to any model that has a foreign key which isn't allowed to be null.
+Before we can use the views we created, we need to hook them up to a URL, just like you would for any other view. Do keep in mind that we need to call the as-view function on them, though. Here is an example of the URLs for the previous views. This pattern is how we normally define CRUD endpoint urls for any entity in a database
+ path('song', views.GetSongs.as_view(), name='songs'),
+ # Create a song
+ path('song/create', views.SaveSong.as_view(), name='Save Song'),
+ #Updates a specified license with information
+ path('song/<int:pk>', views.UpdateSong.as_view(), name='Update Song'),
+ # Deletes a song specified by pk
+ path('song/<int:pk>/delete', views.DeleteSong.as_view(), name='Delete Song'),
+If you are using a pk that is not an int (you manually defined a pk instead of using the default id generated), you'll have to specify that accordingly.
+What if we want more complex behavior beyond the default predefined classes? We can modify them to add more conditions to what is returned.
+In this example, we added an optional way to filter songs by album, using a query_param called album. You'll need to read documentation and tutorials if you want to know more about the custom behavior you can define within your Django REST Framework views.
+class GetSongInAlbum(generics.ListAPIView):
+ serializer_class = SongSerializer
+ def get_queryset(self):
+ queryset = Song.objects.all()
+ alb = self.request.query_params.get('album', None)
+ queryset = queryset.filter(album=alb)
+ return queryset
+If you have a view that isn't necessarily linked to CRUD actions, or has more complex usage and needs more custom defined behavior, you can use APIView.
+Test out your Django REST API
+Compile and run your app with
+$ python manage.py runserver
+Use your bugfixing wizardry to fix any errors that might show up. Now you should be ready to give those predefined endpoints you made for a spin!
+Here's some examples that I did using Postman for API testing. If you used Django REST Framework, it should also come with a built-in API testing tool that you can use in your browser.
+Here's a simple GET request. This is a database read operation, and it's pretty simple. Your browser is making GET requests to every URL you visit while you surf the web.
+| Request + | +
+
+ |
+
| Response + | +
+
+ |
+
Here's a POST request (it's post because we're _creating _or Posting new data) to our create route. We should include the key-value pairs for the song we want to create in the **_Body _**of our request.
+| Request + | +
+
+ |
+
| Response + | +
+
+ |
+
To update, let's follow the URL pattern we defined with the pk of the song we want to update. We can use PUT or PATCH. The info you're sending should be in the _Body _of the request, just like it was for our POST request.
+| Request + | +
+
+ |
+
| Response + | +
+
+ |
+
Let's do the same thing for our deleteSong view, but let's delete Taylor's song this time (pk: 2). I'm sure it was no good anyways.
+| Request + | +
+
+ |
+
| Response + | +
+
+
+ |
+
Let's use our GET view to see what's inside the DB now:
+
**unimportant note: in my zeal to delete taylor's song I had a mishap and accidentally deleted song 3, which I have readded here using a post request. but it's id is now 5 :[
+Finally, let's try out that "song with album" route. We'll add it to our urls.py:
+ # Probably not the best naming convention
+ path('songInAlbum', views.GetSongInAlbum.as_view(), name='Get song in album'),
+
Here's what our request will look like. ^^^^^^^^
+Here's the response:
+
Good to know: Query Parameters
+Notice how our query params don't have to be specified in urls.py - they are dynamically generated from the URL that we try access (everything that comes after a ? in a url is a query parameter, with keys and values separated by '='. If you had multiple query parameters they would be separated by '&'. Next time you're browsing the web, notice how query parameters are used across the different websites you visit!
+It's easy to access query params within Django - see the getSongInAlbum view definition for an example.
+Authtokens, users, logins with Django REST Framework
+Up to now, we've covered the fundamentals of how to create a database, populate it, and create simple endpoints for creating, updating, and destroying. But what happens when we want our system to be used by real users? How do we store their information and their interactions with our system? There are a few important issues that we'll need to address:
+-
+
- How do we make sure that users' personal information like their passcodes are being stored in a secure way that protects them from being stolen? +
- How do we build a system that users can sign up for and log in to? How do we store info about their session? +
- How do we make certain endpoints in our system behave differently depending on the user who is accessing them? +
The answer to these questions can be complicated. In order to save your time and energy, we're going to utilize the resources that Django and Django REST Framework provide for us as much as possible instead of developing our own solutions. Not only is this easier, but it's also much more secure- would you trust a system written from scratch by a novice undergrad student with your password and financial information?
+How do we store user's personal info?
+The answer to this question is usually to use Django's built-in User model. You can read the docs on User models here:
+https://docs.djangoproject.com/en/3.1/ref/contrib/auth/
+The User model contains common fields that will be used by users, and in your serializers you can define which fields are relevant to your use case.
+By default, Django builds the User models for you. You can see them after you runserver and check inside the /admin route.
+We can also utilize the User model to build new endpoints in our API, just like we could with any other model. Here's an example:
+Models.py
+from django.contrib.auth.models import User
+…
+class UserLikesSong(models.Model):
+ user = models.ForeignKey(User, on_delete=models.CASCADE)
+ song = models.ForeignKey(Song, on_delete=models.CASCADE)
+Serializers.py
+class UserLikesSongSerializer(serializers.ModelSerializer):
+ class Meta:
+ model = UserLikesSong
+ fields = ("id", "user", "song")
+ #Id of the rel, Id of the user, ID of the song
+You can now make endpoints with this just like you would with any other model/serializer. This specific example could be used to track what songs the User likes, like in Spotify.
+If you wanted to make a custom User model, you could read more about it here https://simpleisbetterthancomplex.com/tutorial/2016/07/22/how-to-extend-django-user-model.html and do more research, as there are many methods you could use. For basic university usage though, it's 99% of the time going to be faster and easier to roll with the User model they give you out of the box.
+If you want to give different categories of users different permissions, see the_ permissions _section (TODO: this won't be done for a while. In the meantime, these links may help: https://www.django-rest-framework.org/api-guide/permissions/ ← Technical overview
+https://www.django-rest-framework.org/tutorial/4-authentication-and-permissions/ ← Basic usage example)
+Signup, Login, Sessions: How do we do them?
+I highly recommend using Django REST Framework's Authtokens to handle information about user sessions. You can read about authtokens, as well as the other options available, here: https://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication
+To add Authtoken's, make sure the following items appear in settings.py:
+###### You will need to add the REST Framework part.
+###### INSTALLED_APPS should already exist.
+
+REST_FRAMEWORK = {
+ 'DEFAULT_AUTHENTICATION_CLASSES': [
+ 'rest_framework.authentication.TokenAuthentication',
+ ],
+}
+
+INSTALLED_APPS = [ # There will be more here
+ 'rest_framework',
+ 'rest_framework.authtoken',
+]
+
+
+Note: I couldn't get these to work, at least not with authtoken. Leaving them here in case some enterprising individual finds them useful, or message us on Discord if you figure this out :)
+To get REST Framework's default login and logout views (prebuilt), type this in your project's root urls.py file:
+ urlpatterns = [
+ ...
+ path('api-auth/', include('rest_framework.urls'))
+]
+Your path doesn't have to be api-auth, it can be whatever you want.
+To use REST Framework's login view, include this in urls.py:
+ path('whateverPathYouWantToLogin', obtain_auth_token, name='API Token Login'),
+Include this at top of your urls.py:
+from rest_framework.authtoken.views import obtain_auth_token
+When you access this path and provide a real username and password in the request body, then you should receive an authtoken. This authtoken is associated with your account. Store this authtoken in a safe place. Now, you can use it in the "authorization" section of your next HTTP requests, and all requests you make from the client will be associated with the account you just logged in from.
+Creating views for signing up is more difficult.
+| In serializers.py:
+
+
+
+
+
+
+
+
+
+
+
+ +This serializer will make sure that the password that the user makes is valid, and that it's write-only for security purposes. Choose which fields us + |
+
| In views.py:
+
+
+ +… +
+
+
+
+
+
+ |
+
| In urls.py:
+
+ +(you may want to put your register / login views together in a different Django App (so they are in a distinct section of your API) + |
+
| Test Request in Postman:
+
+ +Response from request: +
+ |
+
+
+Now let's quickly do a login from this user we just created!
+I did a login request to the login view I made earlier, but here's what I got:
+
Whenever you see an error like "no such table", that should be a clue that you need to rerun migrations. The app expected there to be a SQL table, but there was none made yet! Running migrations will ensure there is. Recall the commands for migrations are:
++++++
python manage.py makemigrations yourAppName
+++++
python manage.py migrate
In this case, just the second command will be sufficient
+Request:
+
Response:
+
Yay! It worked! Now we can include this token in our request headers to associate all future requests made with the user we logged in.
+In future requests, you should put the token as a value in your request headers, using the key: token.
+
+Depending on the front-end you build, you should use a different way to store the authtoken that you get from logging in. Usually storing in local memory is okay. Do your own research for how to store authtokens with whatever system you are using.
If you want to improve security further, you can use JWT (JSON webtoken) instead, following the instructions here: https://simpleisbetterthancomplex.com/tutorial/2018/12/19/how-to-use-jwt-authentication-with-django-rest-framework.html
+How do we make endpoints behave differently depending on which user is accessing them?
+If a user makes a request while they are authenticated (using authtoken, or some other alternative method), then the system will automatically know what user is associated with the user who made the request.
+You can access the user within a class-based view through
+ self.request.user
+You can use this within your views in a variety of ways: to filter, to make more complex queries, and to check if the user should have access.
+For example, let's make a UserLikesSong endpoint that is limited to the songs that the currently logged in user has liked.
+class GetUserLikesSongs(generics.ListAPIView):
+ def get_queryset(self):
+ queryset = UserLikesSong.objects.all()
+ queryset = queryset.filter(user=self.request.user)
+ # Leftside of filter: from queryset. Rightside: how we're filtering
+ return queryset
+ serializer_class = UserLikesSongSerializer
+We'll cover this in much more detail in the Permissions section.
+Permissions
+NOTE: Everything past here is incomplete - you will need to supplement it with your own research, like I did to make this guide!
+To use generic permissions with Django, all you need to do is:
+-
+
- In your views.py: +
from rest_framework.permissions import IsAdminUser, IsAuthenticated, IsAuthenticatedOrReadOnly
+Now, on any class-based view you want to guard with permissions, you can add the following line:
+class deleteLicenseType(generics.DestroyAPIView):
+ permission_classes = [IsAdminUser]
+ queryset = License_Type.objects.all()
+ serializer_class = License_TypeSerializer
+(this is from a different project)
+You can apply multiple permissions to the same view like this:
+ permission_classes = [IsAdminUser|IsAuthenticatedOrReadOnly]
+Sessions & Cookies
+Sessions/cookies are very easy to make use of with Django. You can use cookies to store information in a user's browser that you'll be able to access in all subsequent requests that a user makes. One example of a good use of sessions/cookies is to store a user's shopping cart content.
+Some great videos for learning about sessions & cookies:
+https://www.youtube.com/watch?v=C75IW38hKI8
+https://www.youtube.com/watch?v=RjykNmVdcgI
+
Deploy to Heroku
+
To get your projects online, you can deploy them to Heroku. Heroku is just one of several possible hosting services for Django- but it's base tier is free, easy to use, and simple to deploy to, so that's what I recommend you use. The biggest downside of using Heroku is that its free tier will automatically shut down your app after a period of downtime, meaning it'll take a long time to respond the next time you try to access it.
+A guide on getting started:
+https://devcenter.heroku.com/articles/django-app-configuration
+Some useful commands:
+++++pip install gunicorn
+
To deploy to Heroku, you will need to make a file called Procfile (no file ending), and add the following gunicorn text to it:
+web: gunicorn yourAppName.wsgi
+This gunicorn file should be at the same level as your manage.py file. When you deploy to Heroku, you should be deploying from this level of the project hierarchy to avoid issues.
+Your remote heroku environment needs to understand what requirements it will need to have to start up. You can do this by providing it with a requirements.txt file which will also be at the same level as your manage.py file.
+To get the right requirements in a .txt file, type
+++++pip freeze > requirements.txt
+
These commands will help initialize your heroku repository:
+++++heroku create
+
++++heroku run python manage.py migrate
+
++++heroku run python manage.py createsuperuser
+
Important: Your database itself will not transfer to Heroku. You will need to recreate all entities, config, and users.
+Tech Start's Git Guide
+
Legend
+=== Beginner Section ===
+-
+
- Getting Started +
- Staging Files & Commits +
- Big Picture & Git Analogy +
- Staging Files & Creating Commits +
- Branches +
- Remote Repositories +
- Merge Conflicts +
- Using Github +
- Our Recommended Git Workflow +
- FAQ +
=== Advanced Section ===
+-
+
- Advanced Staging & Commits +
- Git Stash +
- Git Clean +
- Undoing Commits & Changes +
Unless otherwise noted, all git commands are one line terminal commands
+We are also assuming that you have set up a project at /path/to/project and had “cd’ed” to /path/to/project
+Getting Started - Setting up a Repository
+https://docs.github.com/en/enterprise-server@2.22/get-started
+A Git Repository is virtual storage of your code, allowing you to save versions of your code, as well as share and allow others to edit the code.
+Initializing a new repository: git init
+-
+
- This step is typically used by the project manager, or the owner of the project +
Cloning an existing repository:** git clone [github git link]**
+-
+
- This step is typically used by the project members, or anyones who wants to add onto the projects after it has already been created +
- The github git link can be located on the github repository website under the clone dropdown +
Big Picture & Git Analogy
+Imagine that we have two people working on the same paper remotely, Person A and Person B. Now we notice that Person B is the laziest of the two, so Person A starts the paper.
+Since they are unaware of Google Docs, Person A choses to create a word document on their local machine. This can be seen as Initializing a new repository.
+After working on the paper for a bit, he realizes that Person B also needs to contribute, so they send the paper by email to Person B. This step is equivalent to forking a repository.
+Person B decides that he would prefer to work on the paper by hand, and so he takes the email that Person A sent, and prints it to work on,** cloning the repository **
+Staging Files & Creating Commits
+Git works using units of change called commits. These commits are essentially snapshots of your project. To share any changes, additions, and deletions that you make with other people and upload it to the internet, you will need to package them into a commit first.
+The process of staging files to create a commit is like an assembly line at a factory. The final product of this process is a commit, and you can use commands like
+You can think of the staging area of git (the green box that says "staged changes" in the below diagram) like a box. You can add and remove changes from the box on a per-file-basis.
+Committing is like sealing that box and sticking a label on it. The contents of that box are your changes. But, if there are changes in the untracked or unstaged areas, they will not be included in the commit, because they are outside of the box.
+The following diagram shows how the staging process works, and what commands you can use to move changes on a per-file-basis in between areas. Use the git status command to see a summary of where every change in your project is on this diagram! We recommend using git status frequently.
++
Shown are some common commands for using git to store and prepare the code to be pushed to the remote repository. They are shown in the general order that you want to use them in.
+Below is the legend for some common, optional parameters which are shown
+-
+
- (-text) = optional parameters for command, which are called as is (git command -text) +
- [textName] = optional parameters for command, which are called with your version of the name (git command helloWorld) +
| +git status + | +Shows the status of all changes (changes that have been staged, NOT been staged, or NOT yet been committed). It shows where every change is on the diagram above, and even lists some helpful commands.
+ +It will also say what branch you are on, and if you are ahead or behind the remote version of your branch in terms of commits (more on this in later sections). + +Additionally, if you have a merge conflict, it will show which files caused it. + |
+
| git add [file path] + | +selects the specified files, moves it to the “staging area” and includes it in the next commit
+ +This command will also allow adding a deleted file to be staged, which after being committed and pushed will remove the file from the git branch + +**This command will ignore all files in the “.gitignore” file ** +
|
+
| git commit -m “[commitMessage]” + | +Creates a new commit that includes all changes that you added to the staging area.
+ +You always need to include a name for your commit. It is helpful to be as descriptive as possible! + +If you don't use the -m flag and provide a commit message in quotations, git will make you write a commit message using a text editor. However, this can be very confusing for people especially since your default git text editor is often configured to be VIM (if it is, you can type :qa to exit). For this reason, we recommend always specifying the commit message using -m. + +After you commit, these changes are no longer in the staging area- they are in your commit! +
|
+
| git restore [file path] + | +Discards local changes in a file, thereby restoring its last committed state.
+ +You can use it to quickly get rid of accidental or unnecessary changes, restoring your files to how they used to be before you changed them. + +It won't work if your file is already staged - you'll have to unstage it with git restore --staged first. + |
+
| git restore --staged [file path] + | +Removes the file from the Staging Area, but preserve all modifications you made to it.
+ +You can use it if you accidentally added a file to the staging area whose changes shouldn't be included as part of the next commit you are planning to make. + +If the file was originally untracked, it becomes untracked again. If it was originally a file with unstaged changes, the changes become unstaged again. + |
+
Naming commits
+When you create a commit, you always want to include a descriptive name for the commit that describes exactly what it accomplishes. You wouldn’t label a moving box with kitchen items as simply “stuff.”
+For a video tutorial on staging files, watch https://www.youtube.com/watch?v=KngvG8WzYLU&ab_channel=TheNetNinja
+If you want to learn about additional flags and commands you can use in the process of staging files and adding commits, see the section Advanced Staging & Commits
+Branches
+Branches represent an independent version of the code. They allow new features to be worked on, while ensuring that a working version of the code is not tampered with. This allows large changes to be made to the code base, with little fear of breaking larger projects.
+| git branch + | +Lists all branches in the current repository + | +
| git branch [branchName] + | +Creates a branch called branchName in the current repository.
+ +The created branch's commit history will match the branch you were on when you called git branch. + +We recommend naming branches according to what you want your branch to do. For example, if I was updating the font on a website, I might call my branch updateFont. You may also want to add a prefix to the branch name to indicate it is your branch (this is optional- example, I could call my branch joel/updateFont.) + |
+
| git branch -d [branchName] + | +Deletes the branch called branchName
+ +(You can use -D instead of -d to force delete the specified branch, even is it has unmerged changes. It's typically better to use -d, unless you are 100% sure you will never need the branch you are deleting again) + |
+
| git checkout [branchName] + | +Navigates your current directory to the specified branch, allows you to select which line of development you are working on.
+ +You can only switch branches if you have no unstaged/staged changes in your current branch. If you can't switch branches because of this, see What happens if you can't checkout? for more instructions. + |
+
How should you use branches?
+Whenever you are working on a new feature, or conducting a test/messing with code, you should create a new branch to use.
+Before you make your branch, you should make sure you are creating your branch based on the most recent code. Do **git checkout main **(or master instead of main) to switch to the primary branch of your repository. You will also probably want to do git pull to make sure the primary branch is up to date with the version present on your remote repository (more on this in the next section).
+Now that you are on the primary branch, use **git branch [branchName] **to create a new branch based on the current one. Make sure you name it according to what you aim to accomplish there (see the description of the command above).
+Now that you have created your branch, you'll want to switch to it. Use git checkout [branchName] to switch to your branch. You can do work here and follow the instructions in the staging files and creating commits section to save your changes into commits.
+Eventually, you'll be done using the branch (perhaps you will follow the instructions in the next few sections to push it to your remote repository and use it in a pull request. or perhaps you need to work somewhere else). Either way, you can switch to a different branch with git checkout [branchName].
+If you have completed a pull request for your branch to merge it into a different branch of your project, you no longer need to keep the local copy of your branch. We recommend you use **git branch -d **to delete any branches you will no longer need to use. This makes sure your local repository remains nice and tidy.
+What happens if you can't checkout?
+Git will not let you checkout to switch branches if you have staged or unstaged changes.
+You will have a few choices on what to do:
+-
+
- Restore files to how they originally were (either by manually undoing, or by making use of _git restore, _described in the previous section). Do this if any of your changes are unnecessary or accidental. +
- Create a commit, following instructions from the previous section. Only create a commit if you actually want to save the changes you made. We recommend you avoid making commits on any branches that you share with other people, especially your primary branch (main/master)! +
- Utilize git stash to move changes from one branch to another without needing to commit them. Do this if your changes are intentional, but you wanted them on a different branch than the one you are currently on. This is described in more detail here. +
You can combine these approaches to deal with your changes as necessary.
+Remote Repositories
+When you work with git, you will typically have a _local repository _(the copy of your project that exists on your personal device) and a remote repository (the copy of your project that exists on the internet, usually on a service like GitHub or BitBucket)
+An absolutely core part of using Git is managing the interactions between your local repository and the associated remote repository. The two key commands you will need to learn are **git push **(which you can use to _push _commits from your local repository to the remote repository) and **git pull **(which you can use to _pull _commits from the remote repository and insert them into your own local repository). We have more info on how to use these commands appropriately below.
+A common mistake that newcomers to git will make is assuming that the local repository is the same as the remote repository- when they're actually 2 separate concepts. Your commits won't appear on the remote repository until you manually push them there. If someone else pushes new changes to the remote repository, you won't see their changes on your local repository until you manually pull those changes to your device.
+Most version control related work happens in a local repository(staging, committing, viewing status and logs). When you start working with others on the same project, is when remote repositories come into play. It is like a file server that you use to exchange data with others.
+
| Local + | +Remote + | +
| Are located on the computers of the team members + | +Are on the internet or a local network + | +
| Contains branches, commits, tags + | +Contains branches, commits, tags + | +
| All “coding work” happens only in the local repository, and needs to be made and committed locally. + | +After the work has been committed locally, it can be “uploaded” to the remote repository in order to share with others. + | +
Note: You can name a local branch the same name as the remote branch/repository, but they are NOT the same
+Note: You can also have multiple remote repositories(default is origin). This allows you to have multiple different working branches for new/different features of your code.
+git fetch is what you do when you want to see what everybody else has been working on. it doesn’t force you to actually merge the changes into your repository. This makes fetching a safe way to review commits before integrating them with your local repository.
+https://www.git-tower.com/learn/git/ebook/en/command-line/remote-repositories/introduction/
+| git pull [remoteName] [branchName] + | +Pulls all changes/commits from the remote branch, and inserts them into your current branch
+ +More technical description: fetches from the remote branch (git fetch), and merges your current branch with commits from the remote (git merge) + +**You can “pull” before “pushing” to a branch to avoid unwanted merge conflicts and errors** +
|
+
| git pull origin main + | +fetches commits from the master branch of the origin remote (into the local origin/master branch), and then it merges origin/master into the branch you currently have selected + | +
| git push + | +updates the remote branch with your staged, local commits
+ +**Always “pull” before “pushing” to a branch to avoid unwanted merge conflicts and errors** + |
+
Make sure to PULL before every PUSH if you are collaborating with others.
+Merge Conflicts
+Conflicts generally arise when two people have changed the same lines in a file, or if one developer deleted a file while another developer was modifying it. In these cases, Git cannot automatically determine what is correct. Git will mark the file as being conflicted and halt the merging process. It is then the developers' responsibility to resolve the conflict.
+Resolving merge conflicts is a completely normal part of working collaboratively
+The general steps for resolving merge conflicts can be seen as:
+-
+
- Figure out the conflicts and change them accordingly +
- Re-commit the changes +
- Attempt to merge with the selected branches +
- Read error messages (if any) and repeat if necessary +
Some useful commands for attempting to fix merge conflicts
+| git status + | +Help identify conflicted files + | +
| git log --merge + | +Produces a log with a list of commits that conflict between the merging branches + | +
| git diff + | +Finds the differences between the states of a repository, which helps in preventing conflicts + | +
| git reset --mixed + | +Undo changes to the working directory and staging area + | +
| + | ++ | +
Example of Merge Conflicts shown in Command Line
+
In this case, there are two instances of the file “merge.text” that were modified by different branches/people. Git is unable to determine which lines to keep, as both were changed manually.
+Using GitHub
+GitHub is a company that provides a service of hosting git repositories online. There are many other alternative companies that provide a similar service, like BitBucket, GitLab, and Azure DevOps, but GitHub is the most popular one and we recommend using it in this club.
+The instructions for the rest of this section will focus on GitHub's features. However, almost every feature described here has equivalents in the other git hosts, so if you know how to use one you generally know how to use them all.
+Pull requests
+Video intro to pull requests:
+https://www.youtube.com/watch?v=2VX1ISk9XH8&ab_channel=GitKraken
+A pull request is a way of merging code from one branch of your remote repository into another.
+
You are _requesting _that the _base** **_branch pulls the commits from the compare branch. In the above example, you are requesting that the main branch pulls the commits from the addLaunchEvent.
+We recommend you use pull requests extensively as part of your git workflow.
+We encourage teams to use small, frequent, single-feature PRs. Each PR should have a name that describes exactly what the PR accomplishes. By doing smaller PRs, you will make sure everyone frequently updates their codebase so you don't end up with massive merge conflicts. By limiting your PR to a single feature, you also make it super easy to roll back that feature and reverse all commits in the PR by reverting the PR itself.
+Sometimes, when you create a pull request, it will say there is a merge conflict. If this happens, don't force the PR to merge! Instead, you'll want to resolve the merge conflict. Steps:
+-
+
-
+
On your local machine, checkout to the "compare" branch -
+(ex. git checkout addLaunchEvent)
+
+ -
+
Once you are on the compare branch, do a git pull from the base branch of your PR
+(ex. git pull origin main)
+
+ -
+
This will pull changes from the base into your compare branch. Git will notify you that this caused a merged conflict. This is okay!
+
+ -
+
Resolve the merge conflict according to the instructions in the Merge Conflicts section. You'll need to add and commit the files where you solved the merge conflict.
+
+ -
+
Confirm you have resolved every merge conflict. Try running/building your app again to make sure everything works as expected.
+
+ -
+
Push the commit(s) that solved the merge conflict to your remote compare branch.
+(ex. git push origin addLaunchEvent)
+
+ -
+
The pull request should now update saying there is no merge conflict! You can merge it now, as long as your team approves of it.
+
+
Advantages of pull requests:
+-
+
- They enable your team to do pull request reviews (see more below) +
- Your team can set up custom tests / deployments using CI/CD methods to ensure that your code runs as expected before you merge it +
- It enables you to double check what code you are adding +
- If you ever need to undo a pull request, it's very easy. Most git hosts have an easy way of reverting a pull request- usually it will create a new branch and PR itself, from which you can solve any merge conflicts and quickly roll back the code added from a previous PR. +
- If you stick to coding 1 feature per pull request, it makes it very easy to understand the history of your repository +
Additional readings on pull requests:
+https://product.hubspot.com/blog/git-and-github-tutorial-for-beginners
+https://yangsu.github.io/pull-request-tutorial/
+Pull Request Reviews
+One of the main advantages of pull requests is that they enable you to do a pull request review, ensuring that code that gets pulled into your primary branches has been reviewed by your team to make sure it won't introduce code smells or bugs.
+PRs provide the opportunity to review another developer's code and make sure that it meets the guidelines or practices that your organization or team has. For example, if you have a developer who is more familiar with the architecture of the software system, they can provide valuable input towards making sure that your changes fit within the long term architectural vision of the system. Alternatively, you can have a newer team member who is not yet familiar with the overall code structure and they can add comments to specific parts of the code in a PR to ask for further clarification for why a certain change was made. PRs have been an essential learning tool for me during the past 10 months of my internship.
+Aside from learning, PRs generally serve as a major communication channel for developers in industry, because they provide the opportunity for automated testing and improvements before your code changes are moved to the next deployment stages. One example of automated testing is using linter which is a static code analysis tool used to flag errors in your code such as bugs, stylistics errors, and suspicious constructs, like for example declaring a variable twice.
+Whenever someone wants to merge a pull request, you should require them to get their PR reviewed first. To review a pull request, look at all the changes they made.
+Best Practices for PR Contributors:
+-
+
-
+
Review your PR before adding reviewers.
+-
+
- You may find some work-in-progress or experimental code. There could also be a typo, unintended indentation, or extra line breaks. +
+ -
+
Link your PR to your issue/ticket.
+
+ -
+
Include a brief description of your changes
+
+ -
+
Push small incremental commits to your PR.
+-
+
- You can also mark your PR as a DRAFT PR in GitHub. This pre-commit review can be good practice to check with reviewers if you are going in the right direction before making any more code changes. +
+ -
+
Add additional comments to your PR to guide reviewers through the review.
+-
+
- Highlight areas reviewers should focus on. +
- Clarify changes with comments and additional references. +
- Favor adding code comments over PR comments as the code comments will out survive the PR comments. +
+
Best Practices for Reviewers
+-
+
-
+
Be fast, not furious
+-
+
- Responsiveness and turnaround time are very important to keep PRs healthy and not go stale due to other changes which may have been merged during the time that the PR is open and may even introduce new merge conflicts. +
- Either as a reviewer or as an author, you should keep the conversation actively going until the issue is resolved. +
- As a rule of thumb, if the PR is small or trivial, you should review it within one business day. +
- Plus, context switching is very expensive in industry. Many developers, like myself, have the memory of a goldfish when it comes to remembering the code we wrote a day ago. So, as a courtesy, you can let the developer who opened the PR know if you are planning on looking at their PR at a later time. If there are PRs open, it is also good practice to review them before you create a new one yourself. +
+ -
+
If there are outstanding comments or the PR is in draft mode, do not approve the PR.
+-
+
- Instead, stay involved and follow the discussions and new changes to see how the PR pans out. +
+ -
+
Do NOT rubber stamp reviews.
+-
+
- If you do not understand a change, you can ask for clarification or justification in the comments. +
- You do not have to approve a PR if you are not actually approving the change. You can let the author know that you have completed your review but are not weighing in on the approval. +
- Our TechStart website team's default PR policy requires approvals from 2 different reviewers, but an approval that is rubber stamped can be more harmful than abstaining if it promotes bad practices and bugs to be user-facing. +
+ -
+
Provide constructive comments
+-
+
- Code reviews are an important step in ensuring we build high-quality software products. As a reviewer, it's your job to carefully read and think about the code you are reviewing, and provide constructive feedback or ask questions about the code if things are unclear. +
- If the code isn't formatted correctly, too confusing, contains mistakes, or follows poor conventions, leave a comment to tell them what they did wrong and how they might be able to fix it (but phrase everything constructively! you don't want to seem rude or aggressive). +
- If you disagree with something, give a reason and an example of a better solution. Let the author know exactly what you think is better. +
+
GitHub and other git hosts support adding inline comments, so you can comment on specific areas of the code when necessary. The best place to do this is the "Files Changed" tab of a pull request.
+It is up to them to address every issue that is brought up, and push the changes back to their branch. They should let you know when they've completed everything, and you can check to make sure you're happy with their changes.
+Issues
+GitHub Issues are a great way of keeping track of tasks, bugs, and goals for your projects. We recommend using them as the primary way of assigning tasks to your team and planning out your dev work.
+You can read more about issues here:
+https://guides.github.com/features/issues/
+Our recommended Git workflow
+TODO: Describe how a team of developers should use branches to do versioning correctly
+TODO: Describe possible failures that a developer may encounter in this process because of mistakes they made, and how to recover from them
+Let's assume you have some commits on branch yourLocalBranch, and you want to merge them into a branch on your team's GitHub (which uses the default remote alias, _origin) _called branchYouWantToMergeTo.
+Part 1 - Set up your branch
+-
+
- Ensure you are on the main branch of your repository. It is usually called main or master. If you are not on the main branch, switch to it with **git checkout main **(or master) +
- Pull the most recent version of your main branch from GitHub. You can do this with **git pull origin main **(or master). This will make sure your new branch contains all the most recent changes +
- Create a new branch for yourself. The name of the branch should describe what the code inside will do, and you should prefix it with your name or nickname. For example, git branch joel/changeButtonColor +
- Check out your new branch before you make any changes. Refer to _Branches _if you make any mistakes. Example: git checkout joel/changeButtonColor +
Part 2 - Make your commits
+-
+
- Follow the instructions in the _Staging Files and Adding Commits _section to create a commit containing your desired changes. Use** git status **frequently to make sure you are doing everything correctly. +
Part 3 - Push your commits to origin
+-
+
- Push your branch to origin. Ex. git push origin joel/changeButtonColor +
- Set up a pull request on GitHub, with the base as main (or the branch you want to merge to) and the compare branch as your branch, (ex joel/changeButtonColor) +
- (Only if your pull request indicates you have a merge conflict): DO NOT merge the branch. Instead, do **git pull origin main **(or the branch you want to merge to) on your local machine. This will bring up the merge conflict. +
- Follow the instructions in "Merge Conflicts" to fix any merge conflicts that you get from pulling that branch. Once you have fixed all merge conflicts, remember to double check that your code runs, then git add and git commit your fixes! +
- Push your changes to your remote repository! Do git push origin yourLocalBranch +
- Now that your changes are present on your remote repository, you should create a pull request on GitHub. The base (target branch) should be branchYouWantToMergeTo, and the source should be yourLocalBranch. +
- Check to make sure the pull request says "No merge conflicts". If it does detect merge conflicts, that means you didn't do steps 4-7 correctly, so redo them! +
- Request a reviewer for your pull request. They will read your code and offer suggestions on how to improve it. +
- Resolve the comments of your reviewer. Once they are resolved and your reviewer confirms you can proceed, you can merge the pull request on GitHub. Congratulations! your code is now merged into your project. +
Clean up
+-
+
- Delete your branch on the remote repository +
- Delete your branch on your local system (checkout to main. Then delete with git branch -d yourBranchName) +
Big Picture Git/GitHub Workflow
+Now that you understand the complete process on an individual level, let's take a step back to understand how your team will be using git.
+Here is the Git workflow we recommend:
+(This is what is used at Microsoft. It works well and it's good practice to teach it)
+-
+
- When a team member wants to make changes or additions to the code, they should create a new branch for themselves. The branch name should describe what it does, ex. "fixButtonGlitch" +
- They push their code to a branch on your origin repo that shares the same name +
- When they're ready, they create a Pull Request on GitHub. The PR's source should be their branch, and the destination should be either master or main (whichever your repo is using). +
- They should describe their Pull Request in the description and provide screenshots if applicable +
- They merge their own PR, once the following 3 conditions are met:
+
-
+
- There are no merge conflicts with the base branch +
- If your project has Continuous Integration (which it should), the PR build succeeds +
- At least 2 people have reviewed the code in the PR (more on code reviews later) and all comments from code reviews have been resolved +
+ - Upon merging the PR, they delete their branch. +
FAQ
+List of questions that Joel got often:
+-
+
-
+
What should I do if I made a commit in the wrong branch?
+Refer to undoing changes and commits
+
+ -
+
What should I do if I started work in the wrong branch but not committed yet?
+
+Refer to [undoing changes and commits](#heading=h.2spd0i8oye6o) +
+ -
+
What if I want to revert a commit?
+
+
Refer to undoing changes and commits
+-
+
- How do I push code from my local branch to a remote branch that has a different name?
+
-
+
- In order to push your branch to another remote branch, use the “git push” command and specify the remote name, the name of your local branch as the name of the remote branch +
+ - How do I create a new local branch based on a pre-existing remote branch? +
https://www.git-tower.com/learn/git/faq/checkout-remote-branch/
+-
+
- What do I do if my pull request says it has merge conflicts? +
Advanced Section
+Here are some advanced git commands you can use to boost your git game to the next level. They are not essential to using git, but you may find them helpful. If you're still learning the beginner commands, we recommend focusing on them until you're comfortable with them before worrying about these advanced commands.
+Advanced Staging and Commits
+Here are some additional commands and flags for existing commands that you can use while you are staging files and adding commits.
+If you want descriptions of the basic staging and commits, please see staging files & creating commits in the beginner part of the guide.
+| git status (-s) (-v) + | +You can use the -s and -v flags on git status for the following effects:
+
|
+
| git add
+ +[fileName or folderName] + +(-u) + |
+ You can use the -u flag on git add for the following effects:
+
|
+
| git commit (-a) (-am) "[Commit message here]" + | +You can use the -a and -am flags on git commit for the following effects:
+
|
+
Git Stash
+https://www.atlassian.com/git/tutorials/saving-changes/git-stash
+WIP, should include push, pop, apply, list
+Git Clean
+WIP, should include push, pop, apply, list
+== didnt realize we already have git clean there, but we can do more detail here ==
+Undoing Commits & Changes
+WIP
+Below is the general sequence of commands to check, and undo previous commits. Notice that we must use the commit comments as the easiest factor in differentiating between commits. It is important to use a descriptive comment for each commit.
+| git log + | +Displays old commits with the ID hash and commit comment on the current branch + | +
| git checkout [id hash] + | +Will make your working directory match the exact state of the id’ed commit
+ +*nothing you do here will be saved to the current state of the project (to go back do “git checkout main”) + |
+
| git clean (-f) (-n) + | +‘git clean -n’ shows which UNTRACKED files will be removed, should you do ‘git clean -f’
+ +** good practice is to always -n before you -f ** +
|
+
| git revert + | +Undos a single commit + | +
| git reset [id hash] + | +Goes back to specified commit by removing all subsequent commits + | +
Git Rebase and Git Merge
+WIP
+| git merge [branchName] + | +Merges the specified branch into the branch that your local directory is currently on.
+ +In a typical workflow, you will not need to use this command ever. + +Instead, git pull and pull requests will handle all merging for you. + |
+
Tech Start's API Guide
+
APIs are a ubiquitous component of software engineering. APIs allow different components of a software system to interact with each other in a logical way.
+Learning about APIs is critical to your growth as a software developer. This guide contains links and advice to get you started!
+Introduction
+What is an API?
+
API stands for Application Programming Interface, and in simple words, allows two applications to talk to each other and send information between the two.
+Further reading on the basics of APIs: https://www.plektonlabs.com/api-101-what-are-they-and-how-do-they-work/?gclid=Cj0KCQiAhf2MBhDNARIsAKXU5GRbLqWDWBPN0Zh4ZX6KwjevURl9KmQo0EVBzLn5mcePxaI_l1oWQSQaAkGDEALw_wcB
+Analogy of an API
+Imagine you are sitting in a restaurant with a menu and you are trying to decide what to order. You are one of the applications and in order to get food, the kitchen will act like the other application. It is the system that will “make” you food. The waiter in this scenario will be the API, and he/she delivers the food from one application(the kitchen) to another(you). The waiter is the messenger that takes your request or order and tells the kitchen – the system – what to do. Then the waiter delivers the response back to you; in this case, it is the food.
+How API’s Work
+-
+
- A client application initiates an API call to retrieve information—also known as a request. This request is processed from an application to the web server via the API’s Uniform Resource Identifier (URI) and includes a request verb(see Types of API calls), headers, and sometimes, a request body. +
- After receiving a valid request, the API makes a call to the external program or web server. +
- The server sends a response to the API with the requested information. +
- The API transfers the data to the initial application that requested the information. +
Why would you need an API?
+Many companies have APIs built to allow others to build interesting applications using their company data. APIs also allows a project to be dynamic - it will update the frontend information automatically when the back end is updated. This saves the hassle of going through tons of HTML code updating data one by one.
+Types of APIs
+GraphQL vs Rest
+Reading In favor of GraphQl:
+https://www.howtographql.com/basics/1-graphql-is-the-better-rest/
+Reading In favor of Rest:
+https://www.rubrik.com/blog/technology/19/11/graphql-vs-rest-apis
+Rest APIs
+About
+https://www.ibm.com/cloud/learn/rest-apis
+A REST API is an API that conforms to the design principles of the REST, or representational state transfer architectural style. For this reason, REST APIs are sometimes referred to RESTful APIs.
+What is a RESTful API? https://www.youtube.com/watch?v=y0U-ZxgLu98
+Types of API calls
+
Creating your own API
+Interactive Resource on APIs
+https://apiary.io/how-to-build-api#phase-design
+Tons of help on creating API with different languages https://rapidapi.com/blog/20-tutorials-on-how-to-create-your-own-api-sorted-by-programming-language/
+Explanations of API’s and more in depth language-specific resources
+https://www.moesif.com/blog/api-guide/getting-started-with-apis/
+Using Postman
+What is Postman?
+Postman is a platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs faster.
+Getting Started with Postman: https://www.guru99.com/postman-tutorial.html#1
+Good Postman Series starting with setting up: https://www.youtube.com/watch?v=juldrxDrSH0&ab_channel=AutomationStepbyStep
+Further Resources on APIs
+Collection of Free, premade API’s
+Most premade API’s will have documentation of how to use/maintain them
+https://github.com/public-apis/public-apis
+ +Example of using a premade API
+https://rapidapi.com/blog/how-to-use-an-api/
+GraphQL
+Further Help
+GraphQL Tutorial: https://www.youtube.com/watch?v=ed8SzALpx1Q&ab_channel=freeCodeCamp.org
+What is GraphQL (A really good article): https://www.redhat.com/en/topics/api/what-is-graphql
+Why use GraphQL: https://www.apollographql.com/docs/intro/benefits/
+Getting started with GraphQL: https://www.apollographql.com/docs/intro/benefits/
+GraphQL is split into two main parts, A Schema (Basically a model for the response), and a resolver (a collection of functions that generate response for a GraphQL query. In simple terms, a resolver acts as a GraphQL query handler)
+An article that explains what a Query, Mutation & Subscription are: https://medium.com/software-insight/graphql-queries-mutations-and-subscriptions-286522b263d9
+Tech Start's React Guide
+~~ WIP ~~
++
+
React Essentials
+Check out this video as a crash course to React:
+https://www.youtube.com/watch?v=Ke90Tje7VS0
+If you find this video confusing, or prefer a different one as a React intro, please let us know :)
+If you prefer reading to watching videos, this guide is helpful:
+https://www.freecodecamp.org/news/the-react-handbook-b71c27b0a795/
+Note on functional versus class-based components
+When React was first created, class-based components were the standard. But functional components were introduced later, and they eclipse class-based components in every way.
+Our advice: You should probably never use class-based components!
+Stick to functional components. They are more modern and more versatile.
+Lots of tutorial content online still uses class-based components. If you stumble upon a tutorial or explanation that uses a class-based component, and you're new to React, please search for a functional-component alternative instead!
+Intermediate React
+This section of the guide contains some topics you'll want to learn once you know the essentials of React.
+React Hooks
+In general, a good order of learning hooks is:
+-
+
- useState: https://www.youtube.com/watch?v=4qVNaohzDWU&ab_channel=LogRocket +
- useEffect:https://www.youtube.com/watch?v=gv9ugDJ1ynU&ab_channel=TheNetNinja +
- useRef: https://www.youtube.com/watch?v=yCS2m01bQ6w&ab_channel=Codevolution +
- useCallback: https://www.youtube.com/watch?v=-Ls48dd-vJE&ab_channel=BenAwad +
Other built-in hooks exist, but their uses are more niche, and should only be learned when necessary.
+Creating custom hooks
+You can, and should, create custom hooks in React. Using custom hooks, you can encapsulate a bunch of complicated logic into a simple hook function call, and name it appropriately to describe what your custom hook accomplishes.
+https://www.youtube.com/watch?v=Jl4q2cccwf0&ab_channel=TheNetNinja
+Calling APIs - Part 1
+Calling APIs is a key part of any React App. It's what enables your app to communicate with the outside world - including, presumably, your backend.
+Here's a helpful tutorial on the best practices for calling APIs in React:
+https://www.youtube.com/watch?v=bYFYF2GnMy8
+There's also a part 2:
+https://www.youtube.com/watch?v=1tfd6ANaNRY
+The best ways to fetch data are using the popular package Axos (https://www.npmjs.com/package/axios) or the vanilla JS _fetch _function (https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)
+Once you have parsed the data, you'll probably want to store it in your state somehow (using useState or a redux store).
+It is also good practice to encapsulate your entire API call into a custom hook, and name the hook according to what it does (ex. useFetchPokemonStats). This is also much easier to do if you use a state-management system like Redux, which is described below.
+Calling APIs - Part 2
+The methods described above let you call an API immediately upon rendering a certain component. But what happens if you want to manually trigger an API call (ex. after a certain action or event)?
+Your API call should still use useEffect, and should look mostly like the calls you learned about in Part 1. The 1 difference is you need to guard the useEffect wisely in its dependency array.
+As you recall, the dependency array of a useEffect contains everything that the useEffect depends upon - if any of its dependencies change, it will have a _side effect _of rerunning the useEffect.
+So, you can define a specific variable which only changes when you want your API call to run. You can put that variable in the dependency array of the useEffect. When the action or event that you want to trigger the API call occurs, you should change the trigger variable. This change will trigger the useEffect to run. The trigger variable should never change except when you want the useEffect to run.
+I personally like making my trigger variable an object which also contains any subvariables that my API call needs. So for example, if I was coding a call to a search API that included a text query and target price, my trigger object would contain those.
+Here is an example of a very basic React application that calls an API to perform a search with a custom hook and a useEffect guarded by a trigger object as described above: https://github.com/Tech-Start-UCalgary/react-api-examples/tree/main/js-no-redux
+useSWR
+
useSWR is a useful React hook for data fetching published by Vercel (creators of Next.js).
+SWR stands for stale-while-revalidate. It allows for smart data fetching and encapsulates a lot of advanced fetching logic (like how often should you refetch? should you have a cache?) in a single line of code.
+You should read more about useSWR here:
+ +You can watch a video tutorial here:
+https://www.youtube.com/watch?v=f7yjEdXgGiM
+React with Redux
+Redux is a widely used state container for javascript apps. As soon as your app reaches any level of data complexity, it makes a ton of sense to start using Redux to manage your state.
+A fair warning: Redux will seem complicated at the beginning. That's completely expected! Push through that initial discomfort and you'll get used to it in no time :)
+_ _
+Here is a great introductory video to React-Redux:
+https://www.youtube.com/watch?v=CVpUuw9XSjY
+I highly recommend using **createSlice to setup your Redux Store. **It is a simple way to encapsulate creating actions and slicers in a simple, easy-to-read, easy-to-understand way. Here is a short video that does a great job explaining how to use createSlice:
+https://www.youtube.com/watch?v=e0MEtFaQTZk
+To access your Redux state and update your Redux state in React, I highly recommend using the twin hooks **useSelector **and useDispatch respectively. They are simple, easy, and elegant.
+https://www.youtube.com/watch?v=3zoIigieur0
+~~ Joel will add a full example Redux App here eventually ~~
+React Native
++
Legend
+General
+Setup
+
+First Project
+JavaScript Basics
+Variable
+
+Arrow Functions
+
+Classes
+
+Callbacks
+
+Promises
+
+Await/Async
+React Basics
+Components
+
+Props vs State
+
+Events
+
+Forms in React
+
+Higher Order Components
+
+Hooks
+
+CSS in React
+React Ecosystem
+React Router
+
+Redux
+
+Next.js
+Setup
+Prerequisites
+In order to use create-react-app, you need to have Node.js installed. Node includes npm (the node package manager), and npx (the node package runner).
+You should also have a code editor(like VS Code) installed.
+First Project - Creating create-react-app
+Make sure you cd to the place you'd like your app to live on your hard drive, then run the following in your terminal:
+npx create-react-app name-of-your-app
+**Note: npx create-react-app **will download some Node_Modules for you, but if you are getting a react project that is already made, you will need to type npm install in your terminal.
+JavaScript Basics
+Variables
+Chakra UI is a great frontend ui framework, and it works well with React. Here's a tutorial series that teaches you the basics quickly:
+https://egghead.io/courses/build-a-modern-user-interface-with-chakra-ui-fac68106
+Tech Start's Super Awesome Mega Web Dev Guide:)
+Want to get into web dev? This guide should be your best friend. It covers some of the basic tools and languages you'll need to dive into the world of web development. Rather than providing tutorials, this guide focuses on directing you towards the best free online content to teach you the fundamentals.
+Our advice:
+-
+
- Go through at your own pace! You may need to spend more or less time on a particular topic depending on your experience level. +
- Build practice websites and apps as you learn - you learn by doing. +
- Take your own notes, especially for problems you encounter frequently +
- Go beyond this guide! Tons of resources, courses, and tutorials are out there if you want to learn. Remember: google is a programmer's best friend. +
This guide was originally developed for Tech Start UCalgary, an undergraduate club for software development and entrepreneurship at the University of Calgary. Check us out here -----> https://linktr.ee/techstartuofc <-----
+Or at our website here ---> https://techstartucalgary.com <-----
+If you're interested in contributing to this guide or in building similar guides for other areas (like Git, project management, or mobile development), please send me an email at joel.happ1@ucalgary.ca
+Good luck on your web dev journey and enjoy the guide!
+Part 1 - HTML
+HTML is the building block of all webpages. It's ubiquitous throughout application design - everything from websites to mobile apps to desktop apps use HTML as the base for their frontend.
+
Luckily for you, HTML is also very simple. Don't spend too much time learning it as a beginner - while more advanced HTML concepts do exist, all you need to get started is a basic understanding of how it works.
+To get started, I recommend watching this video and experimenting by building your own HTML document alongside it: https://www.youtube.com/watch?v=UB1O30fR-EE
+To generate a favicon for your site, use this site: https://realfavicongenerator.net/
+No matter which text editor you use (Atom, VSCode, Sublime Text, or something else), I recommend searching for editor plugins to improve your experience writing HTML. Google is your friend here.
+Part 2 - CSS
+If HTML is the backbone of frontends, CSS is the paint. It's an extremely versatile and powerful way of styling and beautifying your content. CSS is easy to get into, but very difficult to master- if front-end development interests you, I recommend dedicating a significant amount of time towards learning CSS.
+
To get started, check out this 1 hour introductory video to CSS:
+https://www.youtube.com/watch?v=yfoY53QXEnI
+Another alternative is this free course on Scrimba, which also covers HTML: https://scrimba.com/learn/htmlcss
+One topic that isn't covered in much detail in the previous video is CSS selectors. For most purposes, you'll probably want to keep your selectors simple (using only class names the vast majority of the time). If you want to learn more about advanced selectors, check out this video: https://www.youtube.com/watch?v=Bcr70LIJcOk
+When working on projects with other people, I recommend avoiding element-level selectors, as they can easily screw with work that others are doing.
+Once you have a good grasp of the basics of CSS, one area that I highly recommend learning is CSS Grid. CSS Grid is a fantastic way of organizing and positioning html content, and it comes with loads of features that make it easy to build adaptive web pages. By combining CSS Grid with CSS breakpoints, you can design interfaces that look great on any size of screen, whether it's a big desktop computer or a small mobile phone.
+Highly recommended course for CSS Grid: https://scrimba.com/learn/cssgrid
+(Warning: CSS grid is not supported by some outdated browsers and browsers like Opera Mini which are used mostly in third world countries to save data. If your intended audience includes these people, do not use CSS Grid.)
+How should you organize and refactor your CSS? I recommend using the BEM strategy for your CSS selectors. https://css-tricks.com/bem-101/
+BEM is a particularly helpful methodology to adopt when you're building websites from components like in React, since you can keep the CSS for each component in a separate file. However, it's far from the only strategy for CSS organization, so you can research and adopt others if they suit your needs better.
+Knowing CSS Flexbox is also helpful for arranging the layouts of websites. It's like
+Finally, here is a great video to watch for some simple, powerful tips for writing modern CSS:
+https://www.youtube.com/watch?v=Qhaz36TZG5Y
++
Part 3 - Javascript
+JavaScript drives the interactivity and functionality of websites. Using it, you can respond to the user's interactions on your website and you can modify the properties of your HTML dynamically.
+
To get started with JavaScript, you can watch this playlist: https://www.youtube.com/playlist?list=PLDyQo7g0_nsX8_gZAB8KD1lL4j4halQBJ
+If you're brand new to programming, you should spend more time learning the fundamentals of JavaScript.
+There are a few areas of JavaScript which may be confusing to any newcomers to the language, even if you have previously learned other languages. I recommend practicing and studying to get used to these features.
+Array functions: https://www.youtube.com/watch?v=rRgD1yVwIvE
+_Asynchronous JavaScript (Await, Promises, Callbacks): _https://www.youtube.com/watch?v=_8gHHBlbziw
+_JSON (JavaScript object notation): _https://www.youtube.com/watch?v=wI1CWzNtE-M
+If you encounter another area of JavaScript that gives you troubles let me know and I'll add a section to this guide.
+3.1 Node.js
+
Here's an introduction to Node.js: JavaScript, but for your operating system instead of your browser. https://www.youtube.com/watch?v=ENrzD9HAZK4 Node.js is frequently used as the backend for the server side of an application or web app.
+Installing Node.js
+We recommend using NVM (node version manager) to install node.js. It allows you to install, uninstall, and switch between different versions of node.js very quickly. Often, you'll need to switch between different versions of node for different projects, so you'll save time by using nvm from the start.
+NVM (Mac/Linux): https://github.com/nvm-sh/nvm
+NVM for windows: https://github.com/coreybutler/nvm-windows
+Once installed, you can type "nvm" in your CLI to see a red list of commands you can use. Follow instructions on GitHub for proper usage!
+Express
+One of the most common Node.js frameworks is Express. Express is an unopinionated_ (meaning, it doesn't force you to do things any particular way) _framework that excels at allowing you to write APIs. We may include more content on Express here in the future.
+
+
3.2** TypeScript**
+TypeScript is a superset of Javascript that introduces new features mostly related to strong typing: this lets you safeguard your variables and functions and helps you catch the most frequent mistakes and bugs from JavaScript code.
+
TypeScript is contained in .ts files, and using a compiler you can compile it into vanilla JavaScript .js files which run as expected on a computer. If you anticipate doing a lot of work with JavaScript, I highly recommend learning TypeScript - although it isn't necessary for every project, it immensely improves the quality of the coding experience and it can guide you towards mastering tricky concepts from JavaScript like promises and callbacks.
+TypeScript tutorial by NetNinja:
+https://www.youtube.com/playlist?list=PL4cUxeGkcC9gUgr39Q_yD6v-bSyMwKPUI
+TypeScript Basics by JavaBrains: (also includes small project incl. API usage)
+https://www.youtube.com/playlist?list=PLqq-6Pq4lTTanfgsbnFzfWUhhAz3tIezU
++
Part 4 - React
+HTML, CSS, and JS are great and all, but what if you want to make a modern, reactive website? Several frontend frameworks exist to empower dynamic, reactive sites, and as of 2021 React is by far the most popular among them. It's a great way to get an introduction into the world of web frameworks and it's a fun tool to use.
+
Here's a good free overview of the basics of React: https://scrimba.com/learn/learnreact
+Plenty of similar courses are available on YouTube and other course platforms.
+When in doubt, consult the React documentation: https://reactjs.org/docs/
+Note that much of the documentation still uses class-based components, as opposed to function-based components. Nowadays, it is 99% preferable to use function-based components whenever possible. It cuts down on the amount of boilerplate you need to write and enables helpful features from hooks.
+Learn more about React Hooks: https://www.youtube.com/watch?v=TNhaISOUy6Q
+The 2 hooks in particular you should be very familiar with:
+-
+
- **useState - **for basic state/data management +
- useEffect - ubiquitous in React. It is used for creating consequences ("effects") for changes in data. It's a critical part of designing React applications to have a functional (not object-oriented) architecture, and you should be using it to create custom hooks. +
Other hooks that are handy to know about are useRef, useCallback, and useLayoutEffect.
+To learn React, you should know HTML, CSS, and JS before. You can also build React apps with TypeScript instead of JavaScript. https://www.typescriptlang.org/docs/handbook/react.html
+React Context API
+The context API is a tool you can use in React to share state from an upper level component (a provider) to its children. If you have state that needs to be shared across many children, you can use the context API rather than pass everything down manually as props.
+To learn about the context API, I recommend watching this video:
+https://www.youtube.com/watch?v=35lXWvCuM8o
+**React Router **
+If you want to make React websites with multiple pages, you can use React Router. It is a package that enables your app to have multiple routes. This series gives a quick overview of React Router:
+https://www.youtube.com/watch?v=aZGzwEjZrXc&list=PL4cUxeGkcC9gZD-Tvwfod2gaISzfRiP9d&index=21
+React Router is lightweight and best suited for very small projects. If you plan on building a larger website with React, we recommend using Next.js instead - it has a lot more features including pre-rendering pages on the server for SEO optimization. Next.js is also widely used and has industry-level support.
+
React Redux is a commonly used package for managing global state. It allows you to take care of state in a global store that can be accessed or modified from anywhere in your application.
+https://www.youtube.com/watch?v=CVpUuw9XSjY
+Using React with Typescript
+Here is a great cheatsheet that you should read to get started with using React in combination with Typescript:
+https://github.com/typescript-cheatsheets/react
+That's it! .. for now :)
+Happy hacking!
+Contributing
+Please submit bug reports, +feature requests, +or general feedback to our +Bug Tracker on GitHub.
+Code contributions
+The easiest way to contribute to this project +is by clicking on the button in the top right corner of any page. +This will open the corresponding page on GitHub, +where you can add or modify content +and then commit the change.
+For more elaborated changes +please:
+-
+
- Fork the project from: https://github.com/techstartucalgary/docs. +
- Follow the tutorial of mdBook, +the tool we use to build and generate this documentation. +
Legal
+-
+
- All of the code that you submit to our code repository +will be licensed under the +Creative Commons CC0 1.0 Universal +and The Unlicense. +
- By submitting code to our code repository you also certify +that you agree to the following +Developer Certificate of Origin. +
Credits
+Special thanks to Kevin Amado1 for writing these docs.
+1
+
+VP Development 2022. Feel free to connect with me on LinkedIn or GitHub, or read my personal website.
+License
+This project is released under either
+the Creative Commons CC0 1.0 Universal license
+and/or under the The Unlicense license,
+at your discretion,
+whose verbatim copies can be found below.
The Unlicense
+-------------
+
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>
+Creative Commons Legal Code
+---------------------------
+
+CC0 1.0 Universal
+
+ CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+ LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+ ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+ INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+ REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+ PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+ THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+ HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+ i. the right to reproduce, adapt, distribute, perform, display,
+ communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+ likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+ subject to the limitations in paragraph 4(a), below;
+ v. rights protecting the extraction, dissemination, use and reuse of data
+ in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+ European Parliament and of the Council of 11 March 1996 on the legal
+ protection of databases, and under any national implementation
+ thereof, including any amended or successor version of such
+ directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+ world based on applicable law or treaty, and any national
+ implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+ surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+ warranties of any kind concerning the Work, express, implied,
+ statutory or otherwise, including without limitation warranties of
+ title, merchantability, fitness for a particular purpose, non
+ infringement, or the absence of latent or other defects, accuracy, or
+ the present or absence of errors, whether or not discoverable, all to
+ the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+ that may apply to the Work or any use thereof, including without
+ limitation any person's Copyright and Related Rights in the Work.
+ Further, Affirmer disclaims responsibility for obtaining any necessary
+ consents, permissions or other rights required for any use of the
+ Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+ party to this document and has no duty or obligation with respect to
+ this CC0 or use of the Work.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/projects/demos/2/index.html b/projects/demos/2/index.html
new file mode 100644
index 0000000..6c6ce6b
--- /dev/null
+++ b/projects/demos/2/index.html
@@ -0,0 +1,257 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Demo #1, February 2nd
+Spirit
+-
+
- Get to know the technical side of your project +a little bit more +and the things you've build so far, +or plan on building. +
- Discovering how we can help you. +
- Help you get out of the way the challenges you see. +
- Monitoring progress is not a goal, +don't feel pressured, +this Demo shouldn't require much preparation, +and instead is more of a sincere conversation. +
Agenda
+We'll go to the table where you are with your team +and talk with you there.
+Driven by the project manager:
+-
+
-
+
Mention your project's name, +the name of its members, +and a short phrase about what your project is about, +and what problem it solves for its consumers.
+
+ -
+
Walk us through your vision:
+-
+
-
+
How do you want your project to look like 3 months for now?
+
+ -
+
Are there any challenges you are facing or may face?
+
+ -
+
What's your number 1 priority as a team right now?
+
+ -
+
What's your number 1 priority as a project manager?
+
+
+ -
+
-
+
Technical overview:
+-
+
- What's your chosen tech stack? +
+
+Note: "Source Code" below means code, diagrams, designs, plots, anything.
+-
+
-
+
Walk us through how a Developer +would clone/access your Source Code +and get started contributing.
+
+ -
+
Walk us through your Source Code.
+
+ -
+
What would be the top 1 thing that if implemented +would make your team contributing experience happier?
+
+
+ -
+
Any closing thoughts?
+
+
May your projects be successful!
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/projects/demos/3/index.html b/projects/demos/3/index.html
new file mode 100644
index 0000000..c70962f
--- /dev/null
+++ b/projects/demos/3/index.html
@@ -0,0 +1,281 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Demo #2, March 16th
+Spirit
+-
+
- Get to know the technical side of your project +a little bit more +and the things you've build so far, +or plan on building. +
- Discovering how we can help you. +
- Help you get out of the way the challenges you see. +
- Monitoring progress is not a goal, +don't feel pressured, +this Demo shouldn't require much preparation, +and instead is more of a sincere conversation. +
Agenda
+We'll go to the table where you are with your team +and talk with you there.
+Driven by the project manager:
+-
+
-
+
Elevator Pitch (30 - 60 seconds)
++
+Goal: keep it short, sweet, and memoriable.
+-
+
- Introduce your project's name and members. +
- Discuss the problem you are attempting to solve +
- What is your solution? +
- How does your solution specifically addresses the problem. +
+ -
+
Progress and Challenges faced since Demo #1:
+-
+
- Recap: What's your chosen tech stack (code, diagrams, designs, plots, ect)? +
- Overall, what has been worked on since Demo #1? +
- What are 3 main sucesses the team is proud of since Demo #1? +
- What are some major challenges that were encountered? How did you overcome them? +
+ -
+
Roadmap for the Final Showcase:
+-
+
- What do you hope to achieve by the Final Showcase on April 29th, 2023? +
- Where do you sit on your timeline for progression for the above goal? +
- Are there any challenges you are currently facing or may face? +
- What resource(s) would be useful to help the team achieve the goal? For example, aid in understanding how to deploy in AWS or the app store from creditable and effective online resources or an industry professional. +
+ -
+
Any closing thoughts?
+
+
May your projects be successful!
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/projects/demos/index.html b/projects/demos/index.html
new file mode 100644
index 0000000..ac7c23a
--- /dev/null
+++ b/projects/demos/index.html
@@ -0,0 +1,215 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Demo #3, April 6th
+Spirit
+-
+
-
+
Do a final showcase simulation.
+
+ -
+
Show the world what you've built.
+
+ -
+
See what other teams have built.
+
+ -
+
No matter what, enjoy the process.
+The amount of hard work, dedication, +and teamwork required to bring an idea to life is immense, +and you should all feel incredibly proud +of what you have accomplished in the last two seasons. +You have overcome countless obstacles and challenges, +honed your skills, and become a better version of yourself. +Now, as you stand at the finish line +and look back on what you have achieved, +take a moment to appreciate how far you have come +and how much you have grown. +Your project is a testament to your passion, creativity, and perseverance, +and it serves as a reminder that with the right mindset and determination, +anything is possible.
+
+
Agenda
+The content is up to you! +The way you deliver your presentation matters, +so feel free to drop here your signature style.
+Just remember that in the final showcase +(and therefore in this demo), +you'll have:
+-
+
-
+
Maximum 15 minutes for your presentation.
+
+ -
+
Maximum 3 minutes for questions and answers.
+
+ -
+
Most of the audience will be completely new to your project.
+
+ -
+
Teams will present in the following order:
+-
+
- Bandist. +
- CyberHire. +
- EasyMeal. +
- LifeLine. +
- AiRM. +
- TechstArcade. +
+ -
+
The judges will score based on +this rubric, +so if you want to win some prizes you may want to optimize for that.
+
+ -
+
Please prepare your responses for the following retrospective questions:
+-
+
- What was the most challenging aspect of the project and how did you overcome it? +
- Looking back, what would you have done differently in terms of planning or execution? +
- How did each team member contribute to the project, and what strengths did they bring to the team? +
- What did you learn from working on this project that you can apply to future projects? +
- In what ways did the project meet or exceed your initial expectations, and why? +
- Did you feel that the project had a meaningful impact, either for your team or for others? +
- What is your plan for the next 3 weeks leading up to the final showcase? +
+
Lastly, just remember to look back on what you have achieved, +and take a moment to appreciate how far you have come +and how much you have grown.
+We all feel very proud of you and believe in you.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/projects/demos/used-by.png b/projects/demos/used-by.png
new file mode 100644
index 0000000..01a7e90
Binary files /dev/null and b/projects/demos/used-by.png differ
diff --git a/projects/license/index.html b/projects/license/index.html
new file mode 100644
index 0000000..2bd0e05
--- /dev/null
+++ b/projects/license/index.html
@@ -0,0 +1,307 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Demos
+At Tech Start UCalgary +all projects are showcased to the world +at the end of each academic year. +In this event, people from different industries and backgrounds +come and give us feedback on the projects, +while also allowing you as a professional and us as a club +to connect and network with different companies.
+This year's showcase is scheduled for April 29th, 2023. +To prepare for the showcase +we want each team to demo their project +on the last dev night of every month until the showcase. +Namely, February 2nd, March 16th, and April 6th, all in 2023.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/projects/motivation/index.html b/projects/motivation/index.html
new file mode 100644
index 0000000..f2111e8
--- /dev/null
+++ b/projects/motivation/index.html
@@ -0,0 +1,230 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A LICENSE.md
+++This is no legal advice.
+
For good or bad, +all of the code that we write +is subject to the following Intellectual Property rights:
+-
+
-
+
Copyright: The right to reproduce, +derivate, +distribute copies, and use the copyrighted work, +and to extend these rights to others.
+
+ -
+
Moral Rights: +The right of being attributed as the author of the work, +and the right to prevent prejudicial distortions of the work (integrity).
+
+
Both concepts can be expanded a little bit more +by reading the following documents +from the U.S. Copyright Office: +1, +2. +It is a very interesting topic.
+For the time being, +think of these rights +as a way for the rights holder +to decide on who and what can be done with the protected work. +Further, without explicit authorization from the rights holder, +you are effectively limited by law from doing anything at all with the work, +unless you can cite Fair Use.
+If you go and read your employee contract, +you'll find that the rights over the work you do for your employer +are "assigned" to the employer +(transferred from you to them), +that you won't exercise your Moral Right of integrity over the work, +and (with luck) +that they'll respect your Moral Right of being attributed, +plus many more clauses that are similar in nature.
+There is also a third concept called +The Public Domain, +which are works to which no Intellectual Property rights apply, +either because they expired, +but usually, because they were expressly waived by the holder.
+
Whether the existence of these rights is good or bad +I leave it for you to think about, +but I'll throw some good articles and books here: +1, +2, +3, +4.
+At Tech Start UCalgary we commit to Open Source everything +under an Open Source Initiative approved license, +but we recommend for source code:
+-
+
- The Unlicense (Public Domain), or +
- The MIT License (Permissive Copyright). +
And for documentation:
+-
+
- CC0 1.0 Universal (Public Domain), or +
- Attribution 4.0 International (Permissive Copyright). +
You can use the following resources to make an informed decision on your project:
+ +We believe the previous licenses are good for the following reasons:
+-
+
- They enable anyone to benefit from the software, +without discrimination, +which aligns well with the club's mission, +and the fact that we are not seeking profit, +but instead, to foster technology. +
- It allows you +or your team, +or anyone in the world, +to continue growing the project +or creating a company out of it in the future. +
Should you not wish to opt-out of the Copyright Monopoly
+by releasing your work into the public domain,
+remember that the rights are yours and not Tech Start UCalgary.
+You haven't signed any Copyright Transfer Agreement
+with us (and you won't)
+so please use Copyright <year> The <project name>'s contributors,
+where the license asks for it.
The projects are yours.
+And in order to ensure future contributions adhere to your license, +make sure to include the following text +somewhere visible in your project, for instance at the end of the README.md:
++++
+- All of the code that you submit to our code repository will be licensed under the
+<license>.- By submitting code to our code repository +you also certify that you agree +to the following Developer Certificate of Origin.
+
This constitutes a very simple +Contributor License Agreement.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/projects/motivation/tiangolo-projects.png b/projects/motivation/tiangolo-projects.png
new file mode 100644
index 0000000..4dee719
Binary files /dev/null and b/projects/motivation/tiangolo-projects.png differ
diff --git a/projects/readme/alejandra-description.png b/projects/readme/alejandra-description.png
new file mode 100644
index 0000000..622db49
Binary files /dev/null and b/projects/readme/alejandra-description.png differ
diff --git a/projects/readme/alejandra-getting-started.png b/projects/readme/alejandra-getting-started.png
new file mode 100644
index 0000000..3d0b538
Binary files /dev/null and b/projects/readme/alejandra-getting-started.png differ
diff --git a/projects/readme/alejandra-readme.png b/projects/readme/alejandra-readme.png
new file mode 100644
index 0000000..3c73400
Binary files /dev/null and b/projects/readme/alejandra-readme.png differ
diff --git a/projects/readme/fast-api-about.png b/projects/readme/fast-api-about.png
new file mode 100644
index 0000000..8605250
Binary files /dev/null and b/projects/readme/fast-api-about.png differ
diff --git a/projects/readme/fast-api-readme.png b/projects/readme/fast-api-readme.png
new file mode 100644
index 0000000..80dd135
Binary files /dev/null and b/projects/readme/fast-api-readme.png differ
diff --git a/projects/readme/fastapi-slogan.png b/projects/readme/fastapi-slogan.png
new file mode 100644
index 0000000..aa34064
Binary files /dev/null and b/projects/readme/fastapi-slogan.png differ
diff --git a/projects/readme/index.html b/projects/readme/index.html
new file mode 100644
index 0000000..221f3d8
--- /dev/null
+++ b/projects/readme/index.html
@@ -0,0 +1,369 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Motivation
+Guess what most of the top Software Developers have in common?
+They all have cool projects!
+torvalds, +dtolnay, +sindresorhus, +donnemartin, +kamranahmedse, +jwasham, +trekhleb, +tiangolo, +gre, +vmihailenco, +twpayne, +brycedrennan, +marten-seemann, +rusty1s, +kripken, +krisnova.
+And those projects are successful:
+
Tech Start UCalgary mission +is to foster an environment +where people can become a better version of themselves +through creating software projects.
+This website will guide you +through the elements that make a project awesome +while emphasizing industry best practices.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/projects/readme/nixos-readme.png b/projects/readme/nixos-readme.png
new file mode 100644
index 0000000..5f7f552
Binary files /dev/null and b/projects/readme/nixos-readme.png differ
diff --git a/projects/readme/prettier-getting-started.png b/projects/readme/prettier-getting-started.png
new file mode 100644
index 0000000..0a0d55a
Binary files /dev/null and b/projects/readme/prettier-getting-started.png differ
diff --git a/projects/readme/prettier-logo.svg b/projects/readme/prettier-logo.svg
new file mode 100644
index 0000000..72252ab
--- /dev/null
+++ b/projects/readme/prettier-logo.svg
@@ -0,0 +1,79 @@
+
+
\ No newline at end of file
diff --git a/projects/readme/prettier-readme.png b/projects/readme/prettier-readme.png
new file mode 100644
index 0000000..bd57071
Binary files /dev/null and b/projects/readme/prettier-readme.png differ
diff --git a/projects/roadmap/eisenhower-matrix.png b/projects/roadmap/eisenhower-matrix.png
new file mode 100644
index 0000000..daa0ac6
Binary files /dev/null and b/projects/roadmap/eisenhower-matrix.png differ
diff --git a/projects/roadmap/index.html b/projects/roadmap/index.html
new file mode 100644
index 0000000..75bda1b
--- /dev/null
+++ b/projects/roadmap/index.html
@@ -0,0 +1,333 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A good
+
+
+
+
+ A good README.md
+A README.md file in the root of the repository
+is going to be the first things your users see.
+GitHub renders this file on the main page of the repository.
This is an example from the NixOS organization:
+
It's important that it's professional and colorful, and that it grabs the user's attention.
+I highly recommend the following elements +are present on the first page:
+-
+
-
+
Logo and name: +A good logo is going to make the project look respected +and professional.
+A good name is able to encapsulate the project's purpose, +or, at the very least, should give the project an identity.
+This is an example from the +Prettier +project:
+
+
It looks good.
+On the other hand, it encapsulates the purpose of the project: +"Making your code prettier".
+
+ -
+
Slogan: +A short, catchy phrase, +summarizing what the project does and its most hot features.
+This is an example from the +FastAPI +project:
++
+FastAPI framework, high performance, easy to learn, fast to code, ready for production.
+Wow. Yes, I want high-performance APIs. +I want things easy to learn, +with no boilerplate, +and robust enough for production.
+While short, +this slogan is very important +because it's displayed on the project card:
+
+
It can be the first thing a new visitor sees +and therefore can be the decisive factor +for a user to click on it.
+It's also displayed on the top of the project home page:
+
+
And sets the expectations for what comes next, +it needs to be good.
+
+ -
+
Description: +Here you will have a few paragraphs to +explain what your project does, +what problem it solves for your users, +and why should a user be using it right now.
+This is an example from the +FastAPI +project:
++
+FastAPI is a modern, fast (high-performance), +web framework for building APIs with Python 3.6+ +based on standard Python type hints.
+The key features are:
+-
+
-
+
Fast: Very high performance, on par with NodeJS and Go (thanks to Starlette and Pydantic). One of the fastest Python frameworks available.
+
+ -
+
Fast to code: Increase the speed to develop features by about 200% to 300%. *
+
+ -
+
Fewer bugs: Reduce about 40% of human (developer) induced errors. *
+
+ -
+
Intuitive: Great editor support. Completion everywhere. Less time debugging.
+
+ -
+
Easy: Designed to be easy to use and learn. Less time reading docs.
+
+ -
+
Short: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs.
+
+ -
+
Robust: Get production-ready code. With automatic interactive documentation.
+
+ -
+
Standards-based: Based on (and fully compatible with) the open standards for APIs: OpenAPI (previously known as Swagger) and JSON Schema.
+
+
* estimation based on tests on an internal development team, building production applications.
+Here the user knows that FastAPI helps build APIs with Python. +They should be using FastAPI right now +because it's fast, intuitive, easy, and so on.
+It's always a good idea to throw a few power-words like: "Fast", "Powerful", "Secure", and "Reliable", +but of course, make sure that this is true.
+You can further improve this section by adding emojis.
+This is an example from the +Alejandra +project:
+
+
To this point, your users should have a clear understanding of:
+-
+
- What problem does your project solve? +
- How does it make the user's life easier? +
- What is special about it? What are the key features? +
But also make sure not to show unnecessary details. +Try to find a balance. +Too short and you'll leave questions unanswered. +Too long and you'll bore or confuse them.
+
+ -
+
-
+
Getting Started: +Users are interested at this point, +they want action now.
+Here we place the shortest path a user can take +to interact with the project. +If there are many, show the fastest/easiest one first, +and then slowly introduce them to the more complex ones.
+This is an example from the +Alejandra +project:
+
+
It simply tells the user to use a web version of the project. +Everybody knows how to click a link, that's easy and nice.
+This is an example from the +Prettier +project:
+
+
Users familiar with Node JS +will find the instructions easy to follow. +However, +some steps could have been removed +and it would have worked the same. +There is no need to overwhelm the user with details at this point. +We can introduce the details later.
+For example, a better version would be:
++
+Install prettier with:
+
+$ npm install --save-dev prettierMake your code beautiful with:
+
+$ npx prettier --write .Remember to keep the first impression simple and intuitive.
+Simplicity is key here.
+
+
Altogether, the following are examples of a good README:
+-
+
-
+
Prettier:
+
+
+ -
+
FastAPI:
+
+
+ -
+
Alejandra:
+
+
+
Lastly, +makeareadme.com also offers some templates and tips.
+You may want to have a look over there.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/projects/roadmap/makes-roadmap.png b/projects/roadmap/makes-roadmap.png
new file mode 100644
index 0000000..2dd9035
Binary files /dev/null and b/projects/roadmap/makes-roadmap.png differ
diff --git a/projects/roadmap/mermaid-diagram-2022-10-26-225437.svg b/projects/roadmap/mermaid-diagram-2022-10-26-225437.svg
new file mode 100644
index 0000000..18197bd
--- /dev/null
+++ b/projects/roadmap/mermaid-diagram-2022-10-26-225437.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/projects/roadmap/milestone-1-plan.png b/projects/roadmap/milestone-1-plan.png
new file mode 100644
index 0000000..b458aff
Binary files /dev/null and b/projects/roadmap/milestone-1-plan.png differ
diff --git a/projects/roadmap/milestones-progress.png b/projects/roadmap/milestones-progress.png
new file mode 100644
index 0000000..fddc571
Binary files /dev/null and b/projects/roadmap/milestones-progress.png differ
diff --git a/projects/roadmap/new-project.png b/projects/roadmap/new-project.png
new file mode 100644
index 0000000..e1a282b
Binary files /dev/null and b/projects/roadmap/new-project.png differ
diff --git a/projects/roadmap/priority-fields.png b/projects/roadmap/priority-fields.png
new file mode 100644
index 0000000..8f14885
Binary files /dev/null and b/projects/roadmap/priority-fields.png differ
diff --git a/projects/roadmap/status-field.png b/projects/roadmap/status-field.png
new file mode 100644
index 0000000..a19cf99
Binary files /dev/null and b/projects/roadmap/status-field.png differ
diff --git a/searcher.js b/searcher.js
new file mode 100644
index 0000000..d2b0aee
--- /dev/null
+++ b/searcher.js
@@ -0,0 +1,483 @@
+"use strict";
+window.search = window.search || {};
+(function search(search) {
+ // Search functionality
+ //
+ // You can use !hasFocus() to prevent keyhandling in your key
+ // event handlers while the user is typing their search.
+
+ if (!Mark || !elasticlunr) {
+ return;
+ }
+
+ //IE 11 Compatibility from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith
+ if (!String.prototype.startsWith) {
+ String.prototype.startsWith = function(search, pos) {
+ return this.substr(!pos || pos < 0 ? 0 : +pos, search.length) === search;
+ };
+ }
+
+ var search_wrap = document.getElementById('search-wrapper'),
+ searchbar = document.getElementById('searchbar'),
+ searchbar_outer = document.getElementById('searchbar-outer'),
+ searchresults = document.getElementById('searchresults'),
+ searchresults_outer = document.getElementById('searchresults-outer'),
+ searchresults_header = document.getElementById('searchresults-header'),
+ searchicon = document.getElementById('search-toggle'),
+ content = document.getElementById('content'),
+
+ searchindex = null,
+ doc_urls = [],
+ results_options = {
+ teaser_word_count: 30,
+ limit_results: 30,
+ },
+ search_options = {
+ bool: "AND",
+ expand: true,
+ fields: {
+ title: {boost: 1},
+ body: {boost: 1},
+ breadcrumbs: {boost: 0}
+ }
+ },
+ mark_exclude = [],
+ marker = new Mark(content),
+ current_searchterm = "",
+ URL_SEARCH_PARAM = 'search',
+ URL_MARK_PARAM = 'highlight',
+ teaser_count = 0,
+
+ SEARCH_HOTKEY_KEYCODE = 83,
+ ESCAPE_KEYCODE = 27,
+ DOWN_KEYCODE = 40,
+ UP_KEYCODE = 38,
+ SELECT_KEYCODE = 13;
+
+ function hasFocus() {
+ return searchbar === document.activeElement;
+ }
+
+ function removeChildren(elem) {
+ while (elem.firstChild) {
+ elem.removeChild(elem.firstChild);
+ }
+ }
+
+ // Helper to parse a url into its building blocks.
+ function parseURL(url) {
+ var a = document.createElement('a');
+ a.href = url;
+ return {
+ source: url,
+ protocol: a.protocol.replace(':',''),
+ host: a.hostname,
+ port: a.port,
+ params: (function(){
+ var ret = {};
+ var seg = a.search.replace(/^\?/,'').split('&');
+ var len = seg.length, i = 0, s;
+ for (;i
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ A RoadMap
+A RoadMap is one of the best ways to manifest the future vision of your product +and the strategy and steps +that will be used for achieving that vision.
+A RoadMap is also a great tool to cooperate with other people +because you can prioritize on it the steps +that are yet to be done, +and see who's working on what, +what progress has been made, +and so on.
+This is an example from the Makes project on GitHub:
+
That's a simple RoadMap, yet it has all the important information. +That's nice!
+I highly recommend you create your RoadMap using the Projects feature on GitHub +because it integrates very well with other GitHub features +like Issues, Pull Requests and Milestones, +but it's also fine if you use Jira +or Trello.
+As a rule of thumb, +anything related to making your project awesome +can (and should) go into the RoadMap. +It's also not limited to just programming tasks, +you could perfectly add to the RoadMap +a meeting with your users, +some market research activity, +or having some Pizza with the team.
+A RoadMap is also a living creature, +it evolves as the project evolves +and you can iterate on it on the go. +Don't worry if you don't get it perfectly from the beginning, +but make sure you have one from the beginning!
+How to create a RoadMap?
+Step 1 - Start with Milestones
+My suggestion is that you start by creating a few +Milestones.
+Think about what your project wants to achieve: +Is it maybe a website that allows you to shorten URLs, +like https://tinyurl.com?
+What's the minimum viable product that you can deliver to your users +so that they can start getting a taste?
+You are right! +An ugly webpage, with an ugly textbox and an ugly button, +that when clicked, gives you a beautifully shortened URL :)
+But that's even too far in the future. +What about making your first Milestone +about having an empty webpage? +Your second Milestone could be having a backend that answers a ping request. +Your third Milestone can be designing the database, +such that it stores the shortened URLs; +and your fourth Milestone can be adding the textbox and button to the front-end, +and an endpoint in the back-end that stores and retrieves the shortened URL.
+You see? +we just planned a minimum viable product, +using an agile methodology.
+Congratulations!
+Step 2 - Split the Milestones in smaller Issues
+Now we can proceed to define the individual tasks (GitHub Issues) +that are needed for completing each Milestone, +and most importantly, +we can assign each member of our team an Issue, +and work collaboratively towards the same goal.
+Bonus points if we can plan it so that they can all work in parallel.
+For example, +for Milestone #1 (Having an empty webpage that the user can access), +we could create the following Issues:
+
In words:
+-
+
- Issue #1: Create a Git repository.
+
-
+
- Priority: Medium. +
- Assignee: John. +
+ - Issue #2, after Issue #1: Add a license.
+
-
+
- Priority: High. +
- Assignee: Olivia. +
+ - Issue #3, after Issue #1: Add a README.md.
+
-
+
- Priority: Medium. +
- Assignee: Jane. +
+ - Issue #4, after Issue #1: Initialize an empty React project.
+
-
+
- Priority: Medium. +
- Assignee: Oliver. +
+ - Issue #5, after Issue #4: Use GitHub actions to deploy the front-end into GitHub pages.
+
-
+
- Priority: Medium. +
- Assignee: John. (John should be free, since finishing #4 means #1 was finished). +
+
Boom! Done.
+Now create more Issues for all of the other Milestones.
+Step 3 - Add your Issues to the RoadMap
+My suggestion for this is to keep it simple. +Avoid too many labels, statuses and complexity.
+First, create a Project (a RoadMap) on GitHub. +This is usually under the Projects tab in the organization view:
+
Then define some statuses:
+
-
+
- 🆕 New: Where you place all of the issues initially. +
- 📋 Backlog: The issues that are yet to be done, and their priority. +
- 🏗 In progress: The issues that are being worked on, and who's working on them. +
- ✅ Done: The issues that have been shipped. +
Then, create a priority field:
+
This will help your team focus on the things +that are more impactful to your project.
+You can use the Eisenhower matrix for this:
+-
+
- 🌋 High priority: Issues that are important and urgent. +
- 🏔 Medium priority: Issues that are important, but not urgent. +
- 🏕 Low priority: Issues that are not important, but may be nice to have someday. +
- 🏝 Never priority: Just close the issue :) don't waste your time on this. +
Now you can start adding Issues to your RoadMap:
+
And see what is the progress towards each Milestone, for example:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/software/devops/index.html b/software/devops/index.html
new file mode 100644
index 0000000..071a25f
--- /dev/null
+++ b/software/devops/index.html
@@ -0,0 +1,238 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Career Paths
+There are several areas of software development that cover different aspects of the software development life cycle. +Usually, people focus on only one or a couple of them. Each of them is a big area on its own and takes years to learn:
+-
+
-
+
Front-end development: This area of software development is concerned with the user interface (UI) and user experience (UX) of software applications. Front-end developers work with technologies like HTML, CSS, and JavaScript to create the visual elements that users interact with.
+
+ -
+
Back-end development: This area of software development is concerned with the server-side of software applications. Back-end developers work with technologies like PHP, Python, Ruby, and Java to create the logic that powers software applications.
+
+ -
+
Full-stack development: Full-stack developers work on both the front-end and back-end of software applications. They have knowledge and skills in both areas of development and can build complete applications from start to finish.
+
+ -
+
Mobile development: This area of software development is concerned with creating applications for mobile devices. Mobile developers work with technologies like Java, Swift, and Kotlin to create native apps for iOS and Android devices.
+
+ -
+
DevOps: DevOps is a methodology that focuses on collaboration between development and operations teams to automate the software delivery process. DevOps engineers use tools like Jenkins, Ansible, and Docker to automate the software development process.
+
+ -
+
Testing and quality assurance: This area of software development is concerned with ensuring that software applications are reliable, bug-free, and meet the requirements of the end-users. Testing and quality assurance engineers use tools like Selenium, JMeter, and LoadRunner to test software applications.
+
+ -
+
Data science and analytics: This area of software development is concerned with creating applications that analyze and interpret data. Data science and analytics engineers work with technologies like Python, R, and SQL to build applications that can perform data analysis, machine learning, and statistical modeling.
+
+ -
+
Artificial intelligence and machine learning: This area of software development is concerned with creating applications that can learn and make decisions based on data. AI and ML developers work with technologies like Python, TensorFlow, and PyTorch to build applications that can perform tasks like natural language processing, image recognition, and predictive modeling.
+
+ -
+
Cybersecurity: This area of software development is concerned with creating secure software applications and protecting them from malicious attacks. Cybersecurity engineers work with technologies like encryption, firewalls, and intrusion detection systems to secure software applications.
+
+ -
+
Cloud computing: This area of software development is concerned with creating applications that can run on cloud computing platforms like Amazon Web Services, Microsoft Azure, and Google Cloud Platform. Cloud developers work with technologies like containerization, serverless computing, and cloud storage to build and deploy applications on the cloud.
+
+ -
+
Embedded systems: This area of software development is concerned with creating software for embedded devices like medical devices, smart appliances, and automotive systems. Embedded systems developers work with technologies like C, C++, and assembly language to create software that runs on these devices.
+
+ -
+
Augmented and virtual reality: This area of software development is concerned with creating applications that allow users to interact with virtual or augmented environments. AR and VR developers work with technologies like Unity, Unreal Engine, and WebXR to build immersive applications for gaming, education, and training.
+
+ -
+
Project management: Involves overseeing the entire software development process from conception to delivery. Project managers are responsible for ensuring that the project is completed on time, within budget, and to the required quality standards.
+
+ -
+
Product owner: The product owner is responsible for defining and prioritizing the features and requirements of a software application. They work closely with development teams, stakeholders, and customers to ensure that the product meets the needs of the users.
+
+ -
+
Technical writing: Technical writers create documentation and user manuals for software applications. They work with developers and other technical experts to create user-friendly documentation that explains how to use the software application.
+
+ -
+
User experience (UX) design: UX designers create the visual design and user experience of software applications. They work with developers to ensure that the application is easy to use and visually appealing.
+
+ -
+
Technical support: Technical support engineers provide support to users who are experiencing issues with software applications. They work with developers to diagnose and resolve technical issues, and provide customer support to users.
+
+ -
+
Technical architecture: Technical architects are responsible for designing the technical architecture of software applications. They work with development teams to ensure that the architecture meets the scalability, security, and performance requirements of the application.
+
+ -
+
Database administration: Database administrators are responsible for managing the data that is used by software applications. They work with developers to design and implement databases, and ensure that the data is stored and managed effectively.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/software/front-end/index.html b/software/front-end/index.html
new file mode 100644
index 0000000..8916ea1
--- /dev/null
+++ b/software/front-end/index.html
@@ -0,0 +1,225 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ DevOps
+DevOps is a software development approach that emphasizes collaboration and communication between software developers and IT operations professionals. The goal of DevOps is to improve the efficiency and quality of software development by breaking down silos and promoting a culture of collaboration, automation, and continuous improvement.
+Traditionally (https://clickup.com/blog/waterfall-project-management/), software development and IT operations have been two separate functions within organizations, with little interaction between them. DevOps seeks to bridge this gap by fostering collaboration between these teams throughout the entire software development lifecycle, from planning and development to deployment and maintenance.
+DevOps involves using tools and practices such as continuous integration, continuous delivery, and infrastructure automation to streamline the software development process and make it more efficient. By automating tasks like testing, building, and deploying software, teams can reduce errors, speed up the development process, and deliver software more quickly and reliably.
+Overall, DevOps is a holistic approach to software development that aims to create a culture of collaboration and continuous improvement, with the goal of delivering software more efficiently and with higher quality.
+How to become a DevOps engineer?
+-
+
-
+
Understand the why and the high-level how (the philosophy).
+For instance:
+-
+
- Get to know The Three Ways: https://itrevolution.com/articles/the-three-ways-principles-underpinning-devops/. +
- Read a book: https://www.amazon.com/DevOps-Handbook-Second-World-Class-Organizations/dp/B09L56CT6N. +
- Win in this game: +https://devops.games/. +
+ -
+
Learn the core skills: DevOps engineers need a strong foundation in software development, You should have a basic understanding of programming languages, and be familiar with version control systems like Git. You should also have experience working with Linux/Unix systems and be familiar with cloud platforms like AWS, Azure, or Google Cloud Platform.
+
+ -
+
Gain experience with DevOps tools and practices: DevOps engineers should be familiar with tools and practices such as continuous integration/continuous delivery (CI/CD), infrastructure as code, configuration management, and monitoring and logging. You can gain experience by working on projects, contributing to open-source projects, or taking online courses.
+
+ -
+
Learn automation: Automation is a key part of DevOps, so you should have experience with containerization tools like Docker and Kubernetes.
+
+ -
+
Build projects: To gain practical experience, you should work on building your own projects or contributing to open-source projects. This will help you to develop your skills and build a portfolio of work that you can show to potential employers.
+
+ -
+
Stay up-to-date: DevOps is a rapidly evolving field, so it's important to stay up-to-date with the latest tools and practices. Attend conferences, read blogs and forums, and participate in online communities to stay current.
+
+ -
+
Apply for jobs: Once you have the skills and experience, it's time to start applying for DevOps engineering jobs. Look for job postings online, reach out to recruiters or companies directly, and attend networking events to make connections in the industry. Be prepared to showcase your portfolio and be able to talk about your skills and experience during interviews.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/tomorrow-night.css b/tomorrow-night.css
new file mode 100644
index 0000000..5b4aca7
--- /dev/null
+++ b/tomorrow-night.css
@@ -0,0 +1,102 @@
+/* Tomorrow Night Theme */
+/* http://jmblog.github.com/color-themes-for-google-code-highlightjs */
+/* Original theme - https://github.com/chriskempson/tomorrow-theme */
+/* http://jmblog.github.com/color-themes-for-google-code-highlightjs */
+
+/* Tomorrow Comment */
+.hljs-comment {
+ color: #969896;
+}
+
+/* Tomorrow Red */
+.hljs-variable,
+.hljs-attribute,
+.hljs-tag,
+.hljs-regexp,
+.ruby .hljs-constant,
+.xml .hljs-tag .hljs-title,
+.xml .hljs-pi,
+.xml .hljs-doctype,
+.html .hljs-doctype,
+.css .hljs-id,
+.css .hljs-class,
+.css .hljs-pseudo {
+ color: #cc6666;
+}
+
+/* Tomorrow Orange */
+.hljs-number,
+.hljs-preprocessor,
+.hljs-pragma,
+.hljs-built_in,
+.hljs-literal,
+.hljs-params,
+.hljs-constant {
+ color: #de935f;
+}
+
+/* Tomorrow Yellow */
+.ruby .hljs-class .hljs-title,
+.css .hljs-rule .hljs-attribute {
+ color: #f0c674;
+}
+
+/* Tomorrow Green */
+.hljs-string,
+.hljs-value,
+.hljs-inheritance,
+.hljs-header,
+.hljs-name,
+.ruby .hljs-symbol,
+.xml .hljs-cdata {
+ color: #b5bd68;
+}
+
+/* Tomorrow Aqua */
+.hljs-title,
+.css .hljs-hexcolor {
+ color: #8abeb7;
+}
+
+/* Tomorrow Blue */
+.hljs-function,
+.python .hljs-decorator,
+.python .hljs-title,
+.ruby .hljs-function .hljs-title,
+.ruby .hljs-title .hljs-keyword,
+.perl .hljs-sub,
+.javascript .hljs-title,
+.coffeescript .hljs-title {
+ color: #81a2be;
+}
+
+/* Tomorrow Purple */
+.hljs-keyword,
+.javascript .hljs-function {
+ color: #b294bb;
+}
+
+.hljs {
+ display: block;
+ overflow-x: auto;
+ background: #1d1f21;
+ color: #c5c8c6;
+}
+
+.coffeescript .javascript,
+.javascript .xml,
+.tex .hljs-formula,
+.xml .javascript,
+.xml .vbscript,
+.xml .css,
+.xml .hljs-cdata {
+ opacity: 0.5;
+}
+
+.hljs-addition {
+ color: #718c00;
+}
+
+.hljs-deletion {
+ color: #c82829;
+}
diff --git a/topics/conflict-management-styles/index.html b/topics/conflict-management-styles/index.html
new file mode 100644
index 0000000..c81c800
--- /dev/null
+++ b/topics/conflict-management-styles/index.html
@@ -0,0 +1,223 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Front End
+A front-end engineer is a software engineer who specializes in building the user interface (UI) and user experience (UX) of a website or application. They are responsible for creating visually appealing and intuitive designs that allow users to interact with the application or website seamlessly.
+The front-end engineer's job involves using various technologies such as HTML, CSS, and JavaScript to build the visual elements of an application or website. They work closely with designers to turn mockups and wireframes into fully functional websites or applications that are easy to use and navigate.
+Front-end engineers also collaborate with back-end engineers to integrate the front-end code with the back-end code, ensuring that the entire system functions correctly. They are responsible for testing and debugging the front-end code, optimizing the code for performance, and ensuring that the website or application is compatible with different browsers and devices.
+How to become a front-end engineer?
+To become a front-end engineer, you will need to follow these general steps:
+-
+
-
+
Learn HTML, CSS, and JavaScript (or TypeScript): HTML is used to structure web pages, CSS is used to style them, and JavaScript is used to add interactivity and dynamic behavior. These are the core technologies used in front-end development.
+
+ -
+
Learn a front-end framework: While it's not strictly necessary, learning a front-end framework like React can help you to build more complex web applications more efficiently.
+
+ -
+
Build projects: To gain practical experience, you should work on building your own projects or contributing to open-source projects. This will help you to develop your skills and build a portfolio of work that you can show to potential employers.
+
+ -
+
Stay up-to-date: Front-end development is a rapidly evolving field, so it's important to stay up-to-date with the latest technologies and best practices. Attend conferences, read blogs and forums, and participate in online communities to stay current.
+
+ -
+
Apply for jobs: Once you have the skills and experience, it's time to start applying for front-end engineering jobs. Look for job postings online, reach out to recruiters or companies directly, and attend networking events to make connections in the industry. Be prepared to showcase your portfolio and be able to talk about your skills and experience during interviews.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/topics/css/index.html b/topics/css/index.html
new file mode 100644
index 0000000..5952b3a
--- /dev/null
+++ b/topics/css/index.html
@@ -0,0 +1,238 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Dealing With Conflict
+Conflict resolution is the process of resolving differences +and disputes between individuals, groups, +or parties through peaceful means. +It involves identifying and addressing the underlying causes of the conflict, +promoting communication and understanding, cooperation, +and finding a mutually acceptable solution, +leading to increased productivity +and satisfaction in personal and professional settings. +When done correctly, +it helps to manage and resolve differences and disputes effectively, +preventing them from escalating into larger and more destructive problems.
+The following document enumerates the trade-offs +of all conflict management styles, +and I highly encourage you to read it.
+https://www.valamis.com/hub/conflict-management-styles.
+Lastly, remember that conflict is not a bad thing. +Instead, learn how to manage it and make the most out of it.
+++ +"If you want to go fast, go alone; if you want to go far, go together."
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/topics/html/index.html b/topics/html/index.html
new file mode 100644
index 0000000..ac0774d
--- /dev/null
+++ b/topics/html/index.html
@@ -0,0 +1,209 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ CSS
+Is only recommended to learn CSS after you are familiar with HTML.
+Fundamentals
+MDN is all you'll need. +Read it from beginning to end: +https://developer.mozilla.org/en-US/docs/Web/CSS.
+Particularly, focus on:
+-
+
- The basic syntax, common attributes (color, font, border) +and basic selectors. +
- The Box Model. +
- CSS Layouts +(Flexbox and Grids as a minimum). +
- Responsive Design and media queries. +
Related utilities:
+-
+
- https://css-tricks.com/snippets/css/a-guide-to-flexbox/ +
- https://css-tricks.com/snippets/css/complete-guide-grid/ +
Popular libraries
+Learn only after you learn the fundamentals:
+ +Advanced
+When you want to architect a big scope system:
+ +Be aware of
+But not necessarily learn them:
+ + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/topics/management-styles/index.html b/topics/management-styles/index.html
new file mode 100644
index 0000000..2caf040
--- /dev/null
+++ b/topics/management-styles/index.html
@@ -0,0 +1,224 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ HTML
+Fundamentals
+MDN is all you'll need. +Read it from beginning to end: +https://developer.mozilla.org/en-US/docs/Learn/HTML.
+You should focus on the basics only (a, button, h1-h6, p, span, lists, div, input, ...).
+HTML is not more complicated than that, learn about CSS next.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/workshops/secrets-management/git-crypt/.gitattributes b/workshops/secrets-management/git-crypt/.gitattributes
new file mode 100644
index 0000000..4239af9
--- /dev/null
+++ b/workshops/secrets-management/git-crypt/.gitattributes
@@ -0,0 +1 @@
+secrets/**/* filter=git-crypt diff=git-crypt
diff --git a/workshops/secrets-management/git-crypt/secrets/dev/password b/workshops/secrets-management/git-crypt/secrets/dev/password
new file mode 100644
index 0000000..33513d3
Binary files /dev/null and b/workshops/secrets-management/git-crypt/secrets/dev/password differ
diff --git a/workshops/secrets-management/git-crypt/secrets/dev/username b/workshops/secrets-management/git-crypt/secrets/dev/username
new file mode 100644
index 0000000..422a0e1
Binary files /dev/null and b/workshops/secrets-management/git-crypt/secrets/dev/username differ
diff --git a/workshops/secrets-management/git-crypt/secrets/prod/password b/workshops/secrets-management/git-crypt/secrets/prod/password
new file mode 100644
index 0000000..dd6d80b
Binary files /dev/null and b/workshops/secrets-management/git-crypt/secrets/prod/password differ
diff --git a/workshops/secrets-management/git-crypt/secrets/prod/username b/workshops/secrets-management/git-crypt/secrets/prod/username
new file mode 100644
index 0000000..2d712f1
Binary files /dev/null and b/workshops/secrets-management/git-crypt/secrets/prod/username differ
diff --git a/workshops/secrets-management/git-crypt/unsafe/key b/workshops/secrets-management/git-crypt/unsafe/key
new file mode 100644
index 0000000..4f7fc25
Binary files /dev/null and b/workshops/secrets-management/git-crypt/unsafe/key differ
diff --git a/workshops/secrets-management/index.html b/workshops/secrets-management/index.html
new file mode 100644
index 0000000..27dd6e9
--- /dev/null
+++ b/workshops/secrets-management/index.html
@@ -0,0 +1,442 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Management Styles
+++A management style is the way +in which a manager works to fulfill their goals. +Management style includes the way that a manager plans, organizes, makes decisions, delegates, +and manages their staff.
+
All management styles are useful depending on the specific scenario, +but it's important to identify when to use which one, +since a wrong management style conduces the team to a dissatisfied, unengaged, inefficient, unmotivated, or frustrated state.
+The following document enumerates the trade-offs +of all management styles and I highly encourage you to read it.
+https://www.valamis.com/hub/management-styles.
+I would just add a last tip here:
+Understand what motivates every person on your team.
+For instance, +remember that a team of volunteers is very different from a team of employees. +On a volunteering team, the motivation factors usually are +self-development and being part of a cause. +The key in this setup +is aligning the team's objectives +with each person's definition of meaningfulness.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/workshops/secrets-management/sops/dev.yaml b/workshops/secrets-management/sops/dev.yaml
new file mode 100644
index 0000000..85c5b1f
--- /dev/null
+++ b/workshops/secrets-management/sops/dev.yaml
@@ -0,0 +1,22 @@
+username: ENC[AES256_GCM,data:kWtcGA==,iv:4+7Usm7Z4QCBENuVKjdUCSVDRxmyMflPUdyW1ClQJzc=,tag:2zxu5/HZ38ZY9ya1Agy8+g==,type:str]
+password: ENC[AES256_GCM,data:k4TjataJMD7XX+vNQOpcgX5zRdHJc86C,iv:8hjdssY3LS3YI+JgrNjoJbvwmenAd1qQ+qNHMNhU4UA=,tag:R0vWZJFITUtMNyQAEX7rbg==,type:str]
+sops:
+ kms: []
+ gcp_kms: []
+ azure_kv: []
+ hc_vault: []
+ age:
+ - recipient: age1ehr903kf80pnd5fzcdssau9pgjv2talthe55e4h8p0tu68exqvvq0za8xx
+ enc: |
+ -----BEGIN AGE ENCRYPTED FILE-----
+ YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSArczlhZlVyNWloOEE4dWl0
+ WWo0S3doWW92R3owRCtJdVAxL2t5a3IySVJZCmZKS2VMQ3pBTHZBNFZXdTl6aTF2
+ VGVxSmxHL0JXaHNVSTU5cndURWswdGMKLS0tIFU0ZkczTmNkK2tjSTN2aTJhOGZI
+ MFNmbC9Yck9rMWJndE9zWWsveURVbU0K1TdgwpHKQ0lCiuNRd79gVwg5Hf2j/INm
+ gysQm/kgmOw53eH8WmY6/nm7Yy/tTtaiu1XPGhmBKt41F9S0rpbrbw==
+ -----END AGE ENCRYPTED FILE-----
+ lastmodified: "2023-02-09T19:14:03Z"
+ mac: ENC[AES256_GCM,data:Ulmk3eHxjFZZk1kfYHfzSdN8jSeaWyW87rzeL+4QvCGUCkhq0KZ72cQBNaesPeh2tM43348fCEhDF7msLXFm6Biz6amSEifh9NpyMFiMrOPwDBe8rWFWhA4xTQCpoTq0X73VonAhZzzoGjHEq5HTb8lGPyx5XlWB6ECbLG6nFwg=,iv:cCKPEDmPbMxT4LbPBzCNrhrcUELA1LCAcs+ZBkrSAyk=,tag:Ns5qeFvoCjqFqoblgzlK4A==,type:str]
+ pgp: []
+ unencrypted_suffix: _unencrypted
+ version: 3.7.3
diff --git a/workshops/secrets-management/sops/prod.yaml b/workshops/secrets-management/sops/prod.yaml
new file mode 100644
index 0000000..fc803d2
--- /dev/null
+++ b/workshops/secrets-management/sops/prod.yaml
@@ -0,0 +1,22 @@
+username: ENC[AES256_GCM,data:vcMex+I=,iv:eY1MrNUES93AGHs24nYVnuqFHYmG1B4i6VqQZ7PVPDA=,tag:/8HMYqx023QudYse7TmwlA==,type:str]
+password: ENC[AES256_GCM,data:O6rHH6bMbcdPfoAyfUrJphlM4iwUcj6p5SxV,iv:qLKe+ZbEvS3jH/nCkSCHsIeYz0ibdPtuZ50HOJHqlNo=,tag:U4zjqgSHAVH4lRffRFXADw==,type:str]
+sops:
+ kms: []
+ gcp_kms: []
+ azure_kv: []
+ hc_vault: []
+ age:
+ - recipient: age1csncr656c24tu37as6h9upms7fyrz8xmc8d6cej07a8ck4wfyv0q8vphqn
+ enc: |
+ -----BEGIN AGE ENCRYPTED FILE-----
+ YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBtOXBkNlc0L3RMSHh1amt6
+ eFRjWXJGejB3aGQ0K2pzT2hicCsxVlI0MXpVCnBTSkpjSGhPRXQ4M3F2YnVRbHZT
+ VkRsTXhTcXFBZkJsbkRKUGdySFZ3S1EKLS0tIDdPeHRaWjYrVTJjWC84b2c2ajQ5
+ cWVVem0xbzJiLzJndG9FVW1NT1BxL2MKOb/COpF4bib+YD0jAyz/VzUQP6D85TGE
+ eFr6umtM8wpauuXqOgVN2xOwIbx6BkXV18w7gPPRgKuHCLjsgpyt0A==
+ -----END AGE ENCRYPTED FILE-----
+ lastmodified: "2023-02-09T19:16:03Z"
+ mac: ENC[AES256_GCM,data:VfYbTj0BvPPHBj7Vsv5MUnzt5qkhUcw+N30La9I/k29rBOVj/Z7xZyEn/5N1A62T/EprB1afXwI3zP2WXiVVy2oieFKCvvxekQtwwbqqEqpBoxR0cawRmAbp+dP57zWVoi6O4wE1FO7tDL94r10Z9w685vSnfWqH3VZJ6TuL5jo=,iv:qROVIqaCoYvGsTx9CACBsb3WtqwI6MbfqJNzMit5T0Y=,tag:BBdl4xQY38jsBgShOy2NXA==,type:str]
+ pgp: []
+ unencrypted_suffix: _unencrypted
+ version: 3.7.3
diff --git a/workshops/secrets-management/sops/unsafe/dev-key.txt b/workshops/secrets-management/sops/unsafe/dev-key.txt
new file mode 100644
index 0000000..47f6c15
--- /dev/null
+++ b/workshops/secrets-management/sops/unsafe/dev-key.txt
@@ -0,0 +1,3 @@
+# created: 2023-02-09T12:09:08-07:00
+# public key: age1ehr903kf80pnd5fzcdssau9pgjv2talthe55e4h8p0tu68exqvvq0za8xx
+AGE-SECRET-KEY-16QDKFYUFY78YQ5D34RFQMT49T2ERHD3K09LP832R6R6QUMSN8AVQU2UWAF
diff --git a/workshops/secrets-management/sops/unsafe/prod-key.txt b/workshops/secrets-management/sops/unsafe/prod-key.txt
new file mode 100644
index 0000000..9420468
--- /dev/null
+++ b/workshops/secrets-management/sops/unsafe/prod-key.txt
@@ -0,0 +1,3 @@
+# created: 2023-02-09T12:15:31-07:00
+# public key: age1csncr656c24tu37as6h9upms7fyrz8xmc8d6cej07a8ck4wfyv0q8vphqn
+AGE-SECRET-KEY-1UEDV76T0EC6WGZT9NF0DA69XJCQQ0HFNPR8PAN7ZEH2S2RKZQD9Q44NSVY
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Secrets Management
+In this Workshop, we'll learn how to properly store the secrets +that your application's source code needs to run +like database connection strings and third-party API access credentials, +and do so even if people have access to your source code.
+We'll be exploring three approaches used in industry, +and talking about when to use one or the other:
+-
+
- Git Crypt. +
- SOPS - My favorite. +
- Hashicorp's Vault. +
We'll also talk a little bit about the Twelve-Factor app, +particularly about factor #3: Configuration.
+Pre-requisites
+To be able to focus on the important aspects of this Workshop (secrets management) +and avoid distractions we'll assume you are familiar with Git +and the command line.
+Please bring your laptop, +the idea is that we'll work together step by step on small exercises +that will teach you each of the tools.
+Only MacOS and Linux are supported. +If you are on Windows, +please install WSL.
+Please come to the workshop with the following tools ready to be used:
+-
+
-
+
A terminal where you can enter commands, set environment variables, etc.
+
+ -
+
Git.
+
+ -
+
Git Crypt:
+Run
+$ brew install git-crypton MacOS, +or$ apt install git-cryptor similar on Linux/WSL.
+ -
+
Sops:
+Run
+$ brew install sopson MacOS, +or$ apt install sopsor similar on Linux/WSL.
+ -
+
Age:
+Run
+$ brew install ageon MacOS, +or$ apt install ageor similar on Linux/WSL.
+ -
+
Vault:
+Please follow the instructions here: +https://developer.hashicorp.com/vault/downloads.
+
+
Why?
+Application secrets are critical for security. +For example, if an attacker discovers the database credentials, +then immediately this attacker would gain access to all of the applications data. +Application secrets is the entrypoint for everything, they are the Keys of Heaven, +and therefore, it's very important to make sure +that only the right people can get access to those secrets.
+In this line of making application secrets be only accessible to the right people +we also need to make sure that developers can only access development secrets. +It's very common to have at least 2 environments: Development and Production, +and to have some kind of segmentation where only super admins can access Production secrets.
+It also doesn't matter if your source code is private, +you still want to protect your secrets because your source code may be leaked, +as it has happened in the past to companies like Twitch.
+There is also an argument about maintainability. +Secrets are also configuration, namely, their values may change over time, +even if the source code doesn't. For this reason it's recommended to +strictly separate them from the source code.
+Workshop Step by Step
+Git-Crypt
+++https://github.com/AGWA/git-crypt
+
Enables you to encrypt/decrypt the parts of a git of repository.
+The good:
+-
+
- Versioned as code. +
- It's simple to use. +
- Great for a simple project, with no compliance needs. +
The bad:
+-
+
- You cannot have multiple keys. All people share the same encryption key, +which means you cannot isolate environments, +and therefore is not that useful in highly regulated industries. +
- Unencrypted secrets touch the disk, +which is not great if someone steals your laptop while unencrypted. +
Steps:
+-
+
-
+
+
As you can see, there are
+devandprodsecrets withusernameandpassword, but they are encrypted, so we cannot see them unless we have they key.
+ -
+
Download the key here
+Note: This should be distributed through a secure channel (e.g. encrypted email). +For the sake of simplicity you can download it here.
+
+ -
+
Now we want to decrypt the secrets, for this we have to:
+
+$ git clone https://github.com/techstartucalgary/Docs.git docs +$ cd docs + +docs $ cat src/workshops/secrets-management/git-crypt/secrets/dev/username + <you should see gibberish> + +# Decrypt +docs $ git-crypt unlock /path/to/key + +# You should see the secrets now +docs $ cat src/workshops/secrets-management/git-crypt/secrets/dev/username +docs $ cat src/workshops/secrets-management/git-crypt/secrets/dev/password + +# Encrypt +docs $ git-crypt lock +docs $ cat src/workshops/secrets-management/git-crypt/secrets/dev/username + <you should see gibberish again> +
+ -
+
The next step is understanding how it works, so essentially you configure which paths of the repository are encrypted in a
+.gitattributesfile like this one: +https://github.com/techstartucalgary/Docs/blob/main/src/workshops/secrets-management/git-crypt/.gitattributes, +where essentially we tell git-crypt to encrypt the files under the secrets/ folder. You can check which files are encrypted with
+$ git-crypt status + not encrypted: src/workshops/secrets-management/README.md + encrypted: src/workshops/secrets-management/git-crypt/secrets/dev/password + encrypted: src/workshops/secrets-management/git-crypt/secrets/dev/username + encrypted: src/workshops/secrets-management/git-crypt/secrets/prod/password + encrypted: src/workshops/secrets-management/git-crypt/secrets/prod/username + not encrypted: src/workshops/secrets-management/git-crypt/unsafe/key +
+
Sops
+++https://github.com/mozilla/sops
+
Enables you to encrypt/decrypt JSON, YAML, or whole files.
+The good:
+-
+
- Versioned as code. +
- You can have multiple keys and access control over a whole file, +great for highly regulated industries. +
- Keys can be connected to an AWS/GCP/Azure identity, +which is great in corporate environments, +and Age/PGP, which is great for other environments. +
The neutral:
+-
+
- Not that easy to use, but reasonable given the features. +
The bad:
+-
+
- Requires some training to get used to it. +
Steps:
+-
+
-
+
Visit https://github.com/techstartucalgary/Docs/tree/main/src/workshops/secrets-management/sops.
+As you can see, there are
+devandprodsecrets withusernameandpassword, but they are encrypted, so we cannot see them unless we have they key.
+ -
+
Download the development key +here +and the production key +here
+Note: This should be distributed through a secure channel (e.g. encrypted email). +For the sake of simplicity you can download it here.
+
+ -
+
Now we want to decrypt the secrets, for this we have to:
+
+$ git clone https://github.com/techstartucalgary/Docs.git docs +$ cd docs + +$ cd src/workshops/secrets-management/sops + +src/workshops/secrets-management/sops $ cat dev.yaml + <you should see gibberish> + +src/workshops/secrets-management/sops $ cat prod.yaml + <you should see gibberish> + +# Decrypt dev secrets with dev key +src/workshops/secrets-management/sops $ SOPS_AGE_KEY_FILE=/path/to/dev/key sops -d dev.yaml + +# Decrypt prod secrets with dev key +src/workshops/secrets-management/sops $ SOPS_AGE_KEY_FILE=/path/to/dev/key sops -d prod.yaml + <you should see a failure, wrong key> + +# Decrypt prod secrets with prod key +src/workshops/secrets-management/sops $ SOPS_AGE_KEY_FILE=/path/to/prod/key sops -d prod.yaml +
+
Vault
++ ++
The good:
+-
+
- Big enterprises like it. Why? Maybe marketing? I assume is because it allows for centralization, which is important if you have hundreds of teams. +
The neutral:
+-
+
- Very flexible. +
The bad:
+-
+
- Another server to maintain. +
- Not versioned as code. +
- Not free. +
++Note: https://vault.kamadorueda.com will be only available during the workshop. If you are following this guide after the workshop, please use your own Vault instance instead.
+
Steps:
+-
+
-
+
Login to the UI at https://vault.kamadorueda.com/ui. The token is
+123.
+ -
+
Let's put and get a secret out of it
+
+$ export VAULT_ADDR=https://vault.kamadorueda.com + +# Login. The token is: 123 +$ vault login + +$ vault kv put secret/your-name password=your-password + +$ vault kv get -field=password secret/your-name +
+ -
+
It's possible to define access control lists, policies, and grant each person a different token, or login with OIDC. It's very flexible.
+
+