diff --git a/github_lab_courses/best_practices.md b/github_lab_courses/best_practices.md new file mode 100644 index 0000000..1a80b4b --- /dev/null +++ b/github_lab_courses/best_practices.md @@ -0,0 +1,61 @@ +# GitHub & Git Best Practices + +*Now that you've mastered the basics read about some best practices to level up your Git. You'll put these into practice many times during the program.* + +## General Tips + +- **_keep commits short_** -> do multiple commits. + +- **_Commit early and often_**: + + It is recommended to commit the early stage of work even if it is unfinished. That way your work history is rich and complete, and it makes your work easily reversible + +- **_Write good commit messages_**: + + The rule of thumb for good commit messages is to separate their subject and body by using one empty line. The subject should not be longer than 50 characters and ought to contain a brief feature / bug fix description, whereas the body should highlight technical modifications in the code. + + For example, this commit message is not ideal: + + ```bash + added styling + ``` + + This is better: + + ```bash + CSS for About page + + - Implement all styling for the About page called for in the design document. [link] + - Add reusable class "contact" that can be used on any
element to implement our custom design for email forms on any page. + - Alter the global rules for link styling to account for changes in the design document. + ``` + + And whatever you do, [don't do this](https://xkcd.com/1296/) :wink:. + +- **_Perform your work in feature branches_**: + + This way all your work is done in isolation on a dedicated branch rather than on the main branch. For example, if you are writing CSS for the About page in your project like in the example in the above section, you should name your branch something like "CSS-for-About-page" so you can isolate all work related to this feature to that branch. + + This approach allows you to work on multiple features at the same time by creating a different branch for each feature. You can then submit multiple pull requests without confusion, and you can iterate without polluting the main branch with potentially unstable, unfinished code. + +- **_Pull fresh changes from the main branch before branching out_**: + + This will ensure that you are up-to-date with the remote branch and other developers. + +- **_Never push directly to the main/development branch_**: + + The `main` and/or `development` branch should be protected from pushing by default. Usually, the `main` and/or `development` branch is where the most stable and reliable code lies, and it is used for production releases. Your future manager will appreciate you knowing this. + +- **_Use a .gitignore file_**: + + Make sure to create a `.gitignore` file in your repository. This file will tell git which files in your project to "ignore" which means they will not be tracked. Files not tracked by git can't be committed, pushed, or pulled when they are on the ignore list. + + The types of files you will want git to ignore will usually be things like **build artifacts** or **operating system files** that can accumulate in your repository as you do your work. Common examples include the `node_modules` directory and `npm-debug.log` files that are generated by using the npm package manager, the `Thumbs.db` file generated by Windows, or the `.DS_Store` file generated by macOS. + + If you're not sure what to put in your `.gitignore` file, have a look at [GitHub's list of sample `.gitignore` files here](https://github.com/github/gitignore) indexed by programming language. freeCodeCamp also has a good [explainer on the topic here](https://www.freecodecamp.org/news/gitignore-what-is-it-and-how-to-add-to-repo/). And the [official documentation](https://git-scm.com/docs/gitignore) on git's website is also worth looking at too. + +- **_Delete local and remote branches after merging_** + + Developers sometimes leave their dead branches in local and remote repositories, which just adds clutter. Once your feature is positively reviewed and merged ✓, make sure you remove your branch to help keep your code clean. + + We know that we have just introduced a lot of new ideas and best practices. **Just try to follow them as often as you can** and don't hesitate to come back to re-read this section when you need a refresher.