diff --git a/wiki/docs/en/onboarding/tracks/index.md b/wiki/docs/en/onboarding/tracks/index.md index 15d39a6..5a08895 100644 --- a/wiki/docs/en/onboarding/tracks/index.md +++ b/wiki/docs/en/onboarding/tracks/index.md @@ -1,7 +1,7 @@ # Onboarding Tracks -- git -- docker +- [git](learn-git/index.md) +- [docker](learn-docker/index.md) - dev web - dev app - devops diff --git a/wiki/docs/en/onboarding/tracks/learn-git/index.md b/wiki/docs/en/onboarding/tracks/learn-git/index.md new file mode 100644 index 0000000..5098d71 --- /dev/null +++ b/wiki/docs/en/onboarding/tracks/learn-git/index.md @@ -0,0 +1,70 @@ +# Introduction to Source Control & Git + +## What is Source Control? +Source control, or version control, is a system that helps **manage** and **track changes** in any digital project over time, which is code in our case. + +It is especially useful for us since developping any software is a team effort, and a system is needed to allow everyone to **collaborate together** without overwriting everyone's changes. + +Additionally, a source control system enables a **detailed history of changes**, allowing someone to easily **revert** to an earlier version without ever losing a single line of code. + +You have probably used some form of Source Control in your life if you've collaborated with a team on any of Google's office suite (Ex. Docs,Sheets)! They allow collaboration on the same document, and provide a history of the changes made. + +### Why do you need a source control system ? +- *Collaboration*: An entire team can work together on the same project, without stepping on anyone's foot +- *Backup*: Any line of code that has been pushed to the source control, will be there forever, no matter what +- *Track changes*: Easily find who added what to a project +- *Branching*: Allows the isolation of certain experimental features on a project, without impacting the main project. + +--- + +## Git (A quick overview) +A source control system is just a bunch of ideas, which anyone can take and create their own functional integration. For us (*and most of the world*), we use [**Git**](https://git-scm.com/). +> Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. + +It was created in 2005 by Linus Torvalds (Creator of Linux) to help the collaborators of the Linux kernel (the heart of a operating system) work together. It has since stood the test of time, and is used by a vast majority of software developpement team. + +It works very well for any project's sizes, while staying efficient. Furthermore, it is a *distributed system*, which means everyone working on a project has a local access to the entire history, without the need for a centralized server. + +### Git's workflow + +```mermaid +sequenceDiagram +box Blue Local + participant Working directory + participant Staging + participant Local Repo +end +box Orange Remote + participant Remote Repo +end + +Working directory->>Staging:git add +Staging->>Local Repo: git commit +Local Repo->>Remote Repo: git push +Remote Repo->>Local Repo: git pull +``` + +Git has 3 primary areas where all the action happens: + +1. **Working directory**: This is the actual files you will be writing your code to ! + +2. **Staging area**: This a a buffer zone where your changes are stored before commiting them. + +3. **Repository (local/remote)**: Also known as a *repo*, this is where all your changes are stored permanently. You have a local repository which can be different from the remote repository since Git is a *distributed* system. + +Git has over a 150 different commands to interact with it ! In our case, we will focus on the following four, and we will see a couple more later on. + +1. **`git add`**: Add or move a change from the working directory into the staging area. + +2. **`git commit`**: Saves the changes you've added from the staging area into your local repo. + +3. **`git push`**: When you are happy with all your changes in your local repo, it is time to push it into the remote repo and make it available to anyone working on the project ! + +4. **`git pull`**: As the name suggests, *pull* retrieves any changes on the remote repo into your local repo. If you've recently `git push` new changes into the remote repo, your colleagues will need to use `git pull` to have acces to them in their own local repo. + +*we can ignore `git checkout` for now.* + +--- + +When you are ready, go on to the [next page](intro_github.md) ! + diff --git a/wiki/docs/en/onboarding/tracks/learn-git/intro_github.md b/wiki/docs/en/onboarding/tracks/learn-git/intro_github.md new file mode 100644 index 0000000..39f060e --- /dev/null +++ b/wiki/docs/en/onboarding/tracks/learn-git/intro_github.md @@ -0,0 +1,34 @@ +# What is Github + +As we've seen, our remote repository need to be hosted and available online. We've chosen [Github](https://github.com/) as our hosting platform for our Git repo because it adds a whole suite of tools, such as issue tracking, code reviews and automations. + +Other popular Git platforms include: + +- [GitLab](https://about.gitlab.com/): Similar to Github, minus some cool tools. + +- [Atlassian Bitbucket](https://bitbucket.org/product/): Deep integration with Atlassian Jira, a popular tool for team management & agile teams. + +- [Azure DevOps](https://azure.microsoft.com/en-ca/products/devops): Microsoft's Git integration for their Azure environnement. Popular at the enterprise level. + +--- + +## Why should you make an account on Github ? +Because of its popularity, Github has became a standard in the industry, and a great way to standout as a professionnal. Employers and recruiters will often look at your Github account, complimentary of a portfolio, to assess coding skills, collaboration ability and code quality. + +> [Here's a great example](https://github.com/SonOfLope) of an account + +If you do not already have a Github account, [create one right now](https://github.com/join) ! Try to keep it up to date with your developping skills. At the end of the onboarding, you will already have a couple projects to add to it ! + +You will see on your account a repository with your own username containing a file named `readme.md`, which is your profil page. +> Markdown (md) is a markup language that let's you easily format text. You can lookup a cheat sheet for all the available formatting. This wiki is written in markdown ! See [how to write it here](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). + +In the following tutorial, we will edit it and make it better, as it is used like a LinkedIn page is used. +### Quick tips for your account: + +- Repositories: Add any projects you are proud of ! (*If you are adding a school project, please talk to your teacher beforehand.*) + +- Commit regularly and contribute to issues: This will show that you are an active user and you have an interest in programming. +--- + +With your fresh account, you are ready to [start using Github](walkthrough_github.md) ! + diff --git a/wiki/docs/en/onboarding/tracks/learn-git/walkthrough_github.md b/wiki/docs/en/onboarding/tracks/learn-git/walkthrough_github.md new file mode 100644 index 0000000..f9a0fd7 --- /dev/null +++ b/wiki/docs/en/onboarding/tracks/learn-git/walkthrough_github.md @@ -0,0 +1,106 @@ +# Your first steps with Git/Github + +## Using Git + +### 1. Download Git CLI + +First, you need to [download the Git Command-Line Interface](https://git-scm.com/downloads). + +### 2. Set up Git + +Once installed, configure your Git credentials with these commands: + +```bash +git config --global user.name "Your Name" +git config --global user.email "yourEmail@example.com" +``` + +### 3. Authenticate with Github + +We need to authenticate our local computer with our account over at Github. Multiple ways are available, but we prioritise SSH since it is the most secure. + +For this step, please head over to [this page](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) for everything you'll need to setup SSH. + +### 4. Clone a repository + +It is now time to start working on a repo ! You can clone your own default repo, and we will add stuff to your `readme.md`. *Make sure to execute this command where you want to add your local repo*. + +```bash +git clone https://github.com/YourUsename/YourUsername.git +``` + +### 5. Adding a file to the repo + +While being in your local repo, create a new file : + +|Linux|Windows| +|-----|-------| +|`touch test.md`|`echo test123 > test.md`| + +Let's now add your file to be tracked by Git: +```bash +git add test.md +``` + +### 6. Commit changes +Add some text to `test.md` and commit them to the history using: +```bash +git commit -m "Added some text" +``` + +The `-m "Added some text"` is an option to add a message along with your commit. It is required in our case. + +### 7. Push changes +After a couple of commits, you would want to share them with everyone by pushing them to the remote repo. +```bash +git push origin main +``` + +> The `origin main` options specifies which branch to push to. + +You can now head over to https://github.com/YourUsername/YourUsername.git to see your new files added to the remote repo. + +### 8. Pull new changes +While on the Github website, add a new file to your remote repo using the button on the top left. As you'll see, it won't be synchronised with your local repo, unless you use the following: +```bash +git fetch origin main +git pull origin main +``` + +> `git fetch` is optional and let's you know what new changes are available before using `git pull` to retrieve them. + +--- + +Now that you've learn the basics of using Git through its CLI, you may now use a visual client such as [Github Desktop](https://desktop.github.com/download/) or the extensions in your IDE (Most of them have one installed by default.). +> While these tools are useful for beginners, a lot of users in the club still prefer to use the CLI for its advanced functionnality + +## Github specifics tools + +### Issues +A big part of why we chose Github is because of its issue tracking. It is a way to track and manage bugs or upcoming features within a repo. We may assign a user to it, or add a comment to someone's suggested fix. + +This wiki is hosted on our repo **Plateforme-Cedille**. You can see its issues [over here](https://github.com/ClubCedille/Plateforme-Cedille/issues). + +### Pull requests + +If anyone started pushing their changes into the remote repo, it would become *chaos*. A pull request (often called a PR) is a proposed change to the codebase, which an approved user (such as the captain of CEDILLE) may pull into the main branch. + +While trying to do a PR, you may get a **merge conflicts** + +### Merge conflicts + +A merge conflict can happen when trying to change a line somebody else has changed. You will have access to a suite of tools that lets you choose between which version you want to keep. + +### Cool stuff + +- Template Repositories: Create repository templates that other developers can use as a starting point. This is great for boilerplate projects or when you want to share a common setup. + +- `readme.md`: This file gives an overview of a projects and how to install/use it. + +- `.gitignore`: Defines which files and directories Git should ignore, often used for files that should not be tracked (Ex. environment files, build outputs and logs) + +- Stashing changes: Use `git stash` to temporarily save your changes without committing them. This is handy when you need to switch branches but have uncommitted work. To retrive them, you may use `git stash pop`. [More information](https://git-scm.com/docs/git-stash) + +- Recovery: If you ever lose a commit or make a mistake, `git reflog` can help you recover it by showing a history of all actions you have executed. + +- Github Actions: Actions are automatic workflows, which are often used to automatically test for bugs, deploy your code etc. For more, see [this guide](/onboarding/tracks/learn-github-actions/) \ No newline at end of file diff --git a/wiki/mkdocs-en.yml b/wiki/mkdocs-en.yml index 3ff7661..653d19a 100644 --- a/wiki/mkdocs-en.yml +++ b/wiki/mkdocs-en.yml @@ -64,7 +64,10 @@ nav: - 'Onboarding intro': onboarding/index.md - Onboarding track: - 'Track - Get started': onboarding/tracks/index.md - - 'Track - Git': onboarding/tracks/git.md + - "Track - Git": + - 'Overview of Git': onboarding/tracks/learn-git/index.md + - 'Introduction to Github': onboarding/tracks/learn-git/intro_github.md + - 'Github walkthrough': onboarding/tracks/learn-git/walkthrough_github.md - "Track - Docker": - 'Learn Docker': onboarding/tracks/learn-docker/index.md - 'Installation': onboarding/tracks/learn-docker/installation.md