Welcome to the Team Development Standards & Best Practices repository. This document outlines the conventions, workflows, and best practices for our team when working with different tools and languages. Our goal is to promote consistency, maintainability, and efficiency in our projects.
In this convention, each developer will be identified by an alias. The alias consists of two characters following the pattern [a-z][a-z0-9].
For example, the developer John Doe might choose the alias jd, while Harry Houdini could select h2.
The main branch is the default branch for all repositories and should always contain the latest stable version of the project.
If you are the sole developer on a project, you may use the main branch for development. However, if multiple developers are collaborating, it is recommended to create separate branches for each feature or bug fix. Developers are encouraged not to push directly to the main branch but instead create a new branch and submit a pull request. If you are working in a team, communicate with the administrator before merging into the main branch.
Branches created from the main branch should follow this naming convention:
<alias>-<feature-name>
For example, if developer John Doe is working on a feature to add a new login page, the branch name should be:
jd-login_page
If <feature-name> consists of multiple words, use underscores _ to separate them.
If you are creating a branch from another branch, use the following naming convention:
<previous-branch-name>-<alias>-<feature-name>
Continuing with the previous example, if Harry Houdini wants to add an animation to the login page, the branch name should be:
jd-login_page-h2-animation
This naming pattern should be followed recursively. That means if another developer wants to add a new feature to Harry Houdini's branch, the branch name should be:
jd-login_page-h2-animation-<alias>-<feature-name>
A repository is, in general, not a cloud storage service. Its main purpose is to save and track changes to the source code. This can include, but is not limited to:
- Source code files
- Configuration files
- Documentation files
- Images and other media necessary for the project
- Data files essential for the project
- Dependency files (e.g.,
requirements.txt,package.json,Manifest.toml,Project.toml)
Avoid including the following files in a repository:
- Compiled binaries or executables
- Log files
- Temporary files
- IDE-specific files (e.g.,
.vscode,.idea,.DS_Store) - Images and media that are not essential for the project
- Data files that are too large, sensitive, or not essential for the project
- Any compiled documentation:
- PDFs from LaTeX
- Rendered HTML files
- Rendered Jupyter notebooks
- Rendered Markdown files
- Rendered Quarto files
- Any other rendered file
Caution
Avoid at all costs including sensitive information in the repository, such as passwords, API keys, or any other confidential data.
Instead, define these in a configuration file that is not included in the repository, and reference them in the code.
Leverage the .gitignore file to exclude unnecessary files and directories from the repository. Remember that it is possible to untrack files that were previously tracked by Git and remove them from the repository history. Always be cautious when doing this, as it can lead to the loss of important information.