-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
consolidate docs and add package manager page
Signed-off-by: pogi7 <[email protected]>
- Loading branch information
Showing
8 changed files
with
76 additions
and
304 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| --- | ||
| sidebar_position: 1 | ||
| sidebar_position: 2 | ||
| --- | ||
|
|
||
| # Artifical Intelligence | ||
|
|
||
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,80 +1,53 @@ | ||
| --- | ||
| sidebar_position: 5 | ||
| sidebar_position: 3 | ||
| --- | ||
|
|
||
| # Package Managers | ||
|
|
||
| Let's discover the basics of pleasant and effective **developer experience in less than 5 minutes**. | ||
| Package managers are an important way to improve the pleasantness and effectiveness of DX. | ||
|
|
||
| ## Version Control | ||
| All package managers are used to add, remove, modify, upgrade, and maintain software. | ||
|
|
||
| [Version control](https://www.atlassian.com/git/tutorials/what-is-version-control) is a way to keep track and manage changes to software code. | ||
| ## OS Level | ||
|
|
||
| Version control can allow developer teams to keep track, mitigate, and resolve errors that may arise from code degradation or human error. | ||
| For most developers an OS (operating system) level package manager will be the most important package manager to use. These package managers install software into a common folder on a computer making managing software much easier. | ||
|
|
||
| ### Git | ||
| ### Windows | ||
|
|
||
| :::tip What is Git? | ||
| By default, Windows does not come with a package manager. | ||
|
|
||
| [Atlassian](https://www.atlassian.com/git/tutorials/what-is-git) does a good job explaining what Git is and the benefits of adopting the technology within a development team. | ||
| The two most common Windows package managers are: | ||
| - [Chocolatey](https://chocolatey.org/) | ||
| - [Scoop](https://scoop.sh/) | ||
|
|
||
| ::: | ||
| ### macOS | ||
|
|
||
| According to [Stack Overflow's 2022 insights](https://survey.stackoverflow.co/2022#version-control-version-control-system), Git is the de facto version control software that personal and professional developers use. | ||
| By default, macOS does not come with a package manager. | ||
|
|
||
| Git is used for managing code locally on a computer. This computer can be a personal computer, a bare metal server, or a cloud instance. | ||
| The most common macOS package manager is: | ||
| - [HomeBrew](https://brew.sh/) | ||
|
|
||
| Git stores code in repos. These local repos can be stored on remote hosting services. | ||
| According to [Stack Overflow's 2022 insights](https://survey.stackoverflow.co/2022#section-most-popular-technologies-other-tools), homebrew is the most widely used OS level package manager. | ||
|
|
||
| ### Github | ||
| ### Linux | ||
|
|
||
| :::tip What is Github? | ||
| By default, Linux comes with a package manager. | ||
|
|
||
| [Github](https://docs.github.com/en/get-started/start-your-journey/about-github-and-git) does a good job explaining how Git and Github interact with each other and the benefits of using Github. | ||
| Each distro of Linux comes with a unique package manager but here are the most common: | ||
| - [DNF](https://en.wikipedia.org/wiki/DNF_(software)) | ||
| - [APT](https://en.wikipedia.org/wiki/APT_(software)) | ||
|
|
||
| ::: | ||
| ## Programming Language Level | ||
|
|
||
| According to [Stack Overflow's 2022 insights](https://survey.stackoverflow.co/2022#section-version-control-version-control-platforms), Github is the most used version control platform that personal and professional developers use. | ||
| Most programming languages have package managers. These package managers are used to get libraries or dependencies from open source repositories that have been published to the registry of the package managers. | ||
|
|
||
| Github is used to store Git repos that can be accessed by developers with the correct authorization. | ||
| Most programming languages have a package manager but here are some for the most popular programming languages: | ||
| - [pyPI](https://pypi.org/) | ||
| - [npm](https://www.npmjs.com/) | ||
| - [maven](https://maven.apache.org/) | ||
|
|
||
| For a developer, Github is used for a development team to see new changes in a codebase and keep track of and manage those changes. | ||
| ## App Level | ||
|
|
||
| An example of a Github repo is shown [here](https://github.com/opencaesar/oml-vision) | ||
| Some large scale apps have package managers as well. This helps since a developer does not need to recreate functionality if it already on the app's package manager registry. | ||
|
|
||
| ## Documenting Code | ||
|
|
||
| Documenting code is very important because it allows you and the rest of the development team to understand how your code works and is supposed to behave. | ||
|
|
||
| Documentation helps dev teams onboard new developers much faster and prevent information from being lost due to turnover or forgetting. | ||
|
|
||
| ### Comments | ||
|
|
||
| Code comments are very helpful for developers because you can put the code documentation right next to the code. | ||
|
|
||
| It is highly recommended to follow the documentation standard for your language that your dev team is using. | ||
|
|
||
| The list includes some of the most widely used programming languages from [Stack Overflow's 2022 insights](https://survey.stackoverflow.co/2022#section-most-popular-technologies-programming-scripting-and-markup-languages): | ||
| - [Python](https://peps.python.org/pep-0257/) | ||
| - [Java](https://www.baeldung.com/javadoc#javadoc-comments) | ||
| - [Typescript](https://tsdoc.org/) | ||
|
|
||
| An example of a Typescript comment that matches a Typescript standard is shown [here](https://github.com/opencaesar/oml-vision/blob/0db2cc46778f1441474c0d4aebc071df453cf52d/controller/src/utilities/loaders/loadCommandFiles.ts#L6-L15) | ||
|
|
||
| ### READMEs | ||
|
|
||
| READMEs are nice to explain higher level functionality of a program, function, class, or piece of software within an app or a piece of software that interacts with your dev team's app. | ||
|
|
||
| READMEs can be included at any level of a Git repo, but generally recommended at the root or top level of a repo so that all developers will know where the README is. | ||
|
|
||
| READMEs can be written in any programming language, but they are generally written in [plain text](https://www.adobe.com/uk/acrobat/resources/document-files/text-files/txt.html) (.txt) or [Markdown](https://www.markdownguide.org/) (.md) files. | ||
|
|
||
| An example of a README.md in a Github repo is shown [here](https://github.com/opencaesar/oml-vision/blob/0db2cc46778f1441474c0d4aebc071df453cf52d/README.md) | ||
|
|
||
| ### Wikis | ||
|
|
||
| Wikis are a good alternative to READMEs when you don't want to store high level documentation about your app inside a Git repo. | ||
|
|
||
| According to [Stack Overflow's 2022 insights](https://survey.stackoverflow.co/2022#section-most-popular-technologies-asynchronous-tools), a very common wiki that dev teams use is [Confluence](https://www.atlassian.com/software/confluence) | ||
|
|
||
| An example of a Confluence page detailing the architecture of an app is shown [here](https://openmbee.atlassian.net/wiki/spaces/OPENMBEE/pages/320765953/Flexo-MMS+Architecture) | ||
| An example of an app having a package manager is Kubernetes's [Helm](https://helm.sh) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| --- | ||
| sidebar_position: 6 | ||
| sidebar_position: 4 | ||
| --- | ||
|
|
||
| # Standard Development Environments | ||
|
|
||
Oops, something went wrong.