-
Notifications
You must be signed in to change notification settings - Fork 1
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Linted markdown #3
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -1,38 +1,46 @@ | ||||||
# git-artifact | ||||||
|
||||||
## The rational for storing artifacts in git | ||||||
|
||||||
I have, over the years in the embbeded enterprise industry, constantly come across many scenarios where zipping, downloading and unzipping generic dependencies and maintaining workspace | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Correct the spelling of "embbeded" to "embedded". - I have, over the years in the embbeded enterprise industry, constantly come across many scenarios where zipping, downloading and unzipping generic dependencies and maintaining workspace
+ I have, over the years in the embedded enterprise industry, constantly come across many scenarios where zipping, downloading and unzipping generic dependencies and maintaining workspace Committable suggestion
Suggested change
|
||||||
has slowed down turn around time for developers and CI system. Git is a fantastic zipper it self and you get integrity of workspaces for free. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Add a comma before "and" to connect two independent clauses. - Git is a fantastic zipper it self and you get integrity of workspaces for free.
+ Git is a fantastic zipper itself, and you get integrity of workspaces for free. Committable suggestion
Suggested change
|
||||||
|
||||||
Git has always been mentioned to be bad for storing artifacts due to the block chain technology and distrubuted architecture. `git-artifact` make sure this problem is handled by storing commits "horisontally" using tags rather than the default "stacked" way. It gives a few advantages compared to standard usage of git: | ||||||
Git has always been mentioned to be bad for storing artifacts due to the block chain technology and distrubuted architecture. `git-artifact` makes sure this problem is handled by storing commits "horisontally" using tags rather than the default "stacked" way. It gives a few advantages compared to standard usage of git: | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Correct the spelling of "block chain" to "blockchain" and "distrubuted" to "distributed". - Git has always been mentioned to be bad for storing artifacts due to the block chain technology and distrubuted architecture.
+ Git has always been mentioned to be bad for storing artifacts due to the blockchain technology and distributed architecture. Committable suggestion
|
||||||
- Firstly; You can garbage collect intermidiate artifacts by just deleting the tag | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Correct "intermidiate" to "intermediate". - Firstly; You can garbage collect intermidiate artifacts by just deleting the tag
+ Firstly; You can garbage collect intermediate artifacts by just deleting the tag Committable suggestion
Suggested change
|
||||||
- Secondly; You only fetch what you need - even without using shallow. | ||||||
|
||||||
### CI/CD integration | ||||||
|
||||||
Triggering of new builds or tests are done the normal way as known from triggering your pipelines of source code - push or pull - simple.. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Remove the extra period. - Triggering of new builds or tests are done the normal way as known from triggering your pipelines of source code - push or pull - simple..
+ Triggering of new builds or tests are done the normal way as known from triggering your pipelines of source code - push or pull - simple. Committable suggestion
Suggested change
|
||||||
|
||||||
### Save money | ||||||
|
||||||
You can save additional license and maintainance cost and/or coqnative load by maintaining and using an additional system for artifacts. You can handle it with your current git repository manager. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Correct "maintainance" to "maintenance" and "coqnative" to "cognitive". - You can save additional license and maintainance cost and/or coqnative load by maintaining and using an additional system for artifacts.
+ You can save additional license and maintenance cost and/or cognitive load by maintaining and using an additional system for artifacts. Committable suggestion
Suggested change
|
||||||
|
||||||
### Producer of artifacts | ||||||
A few remarks, aspects and thoughts when storing the artifacts | ||||||
|
||||||
A few remarks, aspects and thoughts when storing the artifacts | ||||||
|
||||||
- easy to append artifacts as stages evolves with more artifacts | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Start the sentence with an uppercase letter. - easy to append artifacts as stages evolves with more artifacts
+ Easy to append artifacts as stages evolves with more artifacts Committable suggestion
Suggested change
|
||||||
- no need to zip before upload - just commit as the artifact should be used. | ||||||
- easy to add information, environment, tools and git source sha1 in the artifact for traceability and later reproduction | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Start the sentence with an uppercase letter. - easy to add information, environment, tools and git source sha1 in the artifact for traceability and later reproduction
+ Easy to add information, environment, tools and git source sha1 in the artifact for traceability and later reproduction Committable suggestion
Suggested change
|
||||||
- add the source code as a dependency to the artifact. It will then be easy restore the source for diff and debugging | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Add "to" before "restore". - It will then be easy restore the source for diff and debugging
+ It will then be easy to restore the source for diff and debugging Committable suggestion
|
||||||
|
||||||
### Consumer of the artifacts | ||||||
A few remarks, aspects and thoughts when retrieving the artifacts | ||||||
|
||||||
A few remarks, aspects and thoughts when retrieving the artifacts | ||||||
|
||||||
- The consumer do not need anything than standard git | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Correct the verb form "do" to "does". - The consumer do not need anything than standard git
+ The consumer does not need anything than standard git Committable suggestion
Suggested change
|
||||||
- Pipelines just consumes the artifact unzip and ready to use as they were produced | ||||||
- Use your favorit git dependency system like submodules(this is the correct way for submodule usage btw ), repo tool or .. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Remove the extra period. - Use your favorit git dependency system like submodules(this is the correct way for submodule usage btw ), repo tool or ..
+ Use your favorite git dependency system like submodules (this is the correct way for submodule usage btw), repo tool or . Committable suggestion
Suggested change
|
||||||
- Even a consumer can be a producer by adding further artifacts on top the consumed commit with a new commit and tag | ||||||
- git understand the content in workspace and git clean does not remove artifacts in contrast to downloaded artifacts | ||||||
|
||||||
## How is it done | ||||||
|
||||||
Git normally stacks the history hence you cannot delete commit in the middle of the history. `git-artifact` make a "horizontal" history - i.e the commits are not stacked on top of each other, but next to each other. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Correct the sentence structure for clarity and add the missing period in "i.e.". - Git normally stacks the history hence you cannot delete commit in the middle of the history. `git-artifact` make a "horizontal" history - i.e the commits are not stacked on top of each other, but next to each other.
+ Git normally stacks the history, hence you cannot delete a commit in the middle of the history. `git-artifact` makes a "horizontal" history - i.e., the commits are not stacked on top of each other, but next to each other. Committable suggestion
Suggested change
|
||||||
|
||||||
The history is basically like this | ||||||
The history is basically like this: | ||||||
|
||||||
``` mermaid | ||||||
%%{init: { | ||||||
|
@@ -66,96 +74,111 @@ gitGraph: | |||||
commit id: "2.0/test" tag: "2.0/test" | ||||||
``` | ||||||
|
||||||
### Prerequisites | ||||||
|
||||||
`git-artifact` has all the functions available that make the above history natural workflow. | ||||||
|
||||||
### Prerequisites | ||||||
The tool uses tags hence the producer need to tag push-rights. It is also beneficial to have tag delete-rights to clean old artifacts. | ||||||
|
||||||
It can also run in branch mode. It can maintain a `latest` branch which needs to be force pushed or delete + push rights. The concept is similar to docker concept of `<image>/latest`. It is only important if you want to use tracking branches without using `git-artifact`. It could be in context of `submodules` or `repo manifests`. | ||||||
|
||||||
### Installation | ||||||
|
||||||
Download or clone this repo (`git-artifact`) and add make it available in the PATH. Given that `git-artifact` is in the PATH, then `git` can use it as an command like `git artifact`. It is now integrated with git and git is extended. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Use "a" instead of "an" before "command". - Given that `git-artifact` is in the PATH, then `git` can use it as an command like `git artifact`.
+ Given that `git-artifact` is in the PATH, then `git` can use it as a command like `git artifact`. Committable suggestion
Suggested change
|
||||||
|
||||||
## Getting started | ||||||
|
||||||
First you need to create a repository in your git repository manager. You can either choose to initialize the repo, but `git artifact` also have command to do that and it states that this repository is "special" repository containing git artifacts. | ||||||
|
||||||
### Initialize the repository | ||||||
|
||||||
Let us now initialized a repo: | ||||||
``` | ||||||
|
||||||
```bash | ||||||
git artifact init --url=<remote_url> --path my-git-artifact-path | ||||||
``` | ||||||
|
||||||
### Add the artifact | ||||||
|
||||||
The repository and path initialize above ready to use. Copy the artifacts to your path in the folder structure the "constumer" desire it. There is not reason to tar or zip it. Git will handling this for optimized storage and easiness. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Correct grammatical errors. - The repository and path initialize above ready to use. Copy the artifacts to your path in the folder structure the "constumer" desire it. There is not reason to tar or zip it. Git will handling this for optimized storage and easiness.
+ The repository and path initialized above are ready to use. Copy the artifacts to your path in the folder structure the "consumer" desires it. There is no reason to tar or zip it. Git will handle this for optimized storage and easiness. Committable suggestion
Suggested change
|
||||||
|
||||||
``` | ||||||
```bash | ||||||
cd my-git-artifact-path | ||||||
cp -rf <build-dir>/my.lib /include . | ||||||
git artifact add-n-push -t v1.0 | ||||||
``` | ||||||
|
||||||
The artifact v1.0 is now commited, pushed _and_ importantly - the workspace is set back to the default branch of the remote repository. It is now ready to make a new artifact based on the default branched | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Correct "commited" to "committed". - The artifact v1.0 is now commited, pushed _and_ importantly - the workspace is set back to the default branch of the remote repository.
+ The artifact v1.0 is now committed, pushed _and_ importantly - the workspace is set back to the default branch of the remote repository. Committable suggestion
Suggested change
|
||||||
|
||||||
## Finding and getting artifacts | ||||||
|
||||||
Firstly clone the git artifact repository. Note that you only clone and get the default branch | ||||||
``` | ||||||
|
||||||
```bash | ||||||
git artifact clone --url=<remote> --path my-git-artifact-path | ||||||
cd my-git-artifact-path | ||||||
```` | ||||||
|
||||||
### Find the latest using pattern | ||||||
``` | ||||||
|
||||||
```bash | ||||||
git artifact find-latest -r 'v*.*' | ||||||
``` | ||||||
|
||||||
### Download and checkout the latest | ||||||
``` | ||||||
|
||||||
```bash | ||||||
git artifact fetch-co-latest --regex 'v*.*' | ||||||
``` | ||||||
|
||||||
## Appending to an artifact | ||||||
|
||||||
You can append to an artifact with advantage. Let say you create a library and you run a lot of tests in a later stage and the result is a test report. You can then just add that on top of the library tag. | ||||||
|
||||||
- Download and checkout the artifact ( see above ) | ||||||
- Add a new artifact ( see above ) | ||||||
|
||||||
You should of course consider this in your naming convension. Consider something like this: | ||||||
``` | ||||||
|
||||||
```bash | ||||||
vX.Y.Z/release-note | ||||||
vX.Y.Z/test | ||||||
vX.Y.Z/src | ||||||
vX.Y.Z/lib | ||||||
``` | ||||||
|
||||||
### Add the source code that was used to build the artifact | ||||||
|
||||||
The source code in many companies and open-source projects are free to view, debug and edit. You can make it easy accessable by adding the source code as submodule and sha1 in to the artifact history. It sounds odd, but it gives the developers easy access to checkout the correct version that was used to build artifact. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Correct "checkout" to "check out". - It sounds odd, but it gives the developers easy access to checkout the correct version that was used to build artifact.
+ It sounds odd, but it gives the developers easy access to check out the correct version that was used to build the artifact. Committable suggestion
Suggested change
|
||||||
|
||||||
This way it actually possible to create a full block-chain of everything that was involved in producing a product. | ||||||
|
||||||
## Add information to the annotated tag | ||||||
|
||||||
TODO: option for file or string | ||||||
|
||||||
## Pruning / cleaning artifacts | ||||||
TODO: based on count.. | ||||||
|
||||||
|
||||||
TODO: based on count.. | ||||||
|
||||||
## Advanced | ||||||
|
||||||
### LFS | ||||||
`git artifact` work great out of the box without any extensions like LFS. It can though still be interesting to commit an `git-lfs` configuration to the default branch. | ||||||
- Artifact sets that can many common binary/large files from version to version will then be able to detect that it already have have this file in the LFS storage and do not have to fetch/push it again. | ||||||
|
||||||
`git artifact` work great out of the box without any extensions like LFS. It can though still be interesting to commit an `git-lfs` configuration to the default branch | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Start the sentence with an uppercase letter. - `git artifact` work great out of the box without any extensions like LFS.
+ `Git artifact` works great out of the box without any extensions like LFS. Committable suggestion
Suggested change
|
||||||
|
||||||
- Artifact sets that can many common binary/large files from version to version will then be able to detect that it already have have this file in the LFS storage and do not have to fetch/push it again. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Correct the repeated word "have". - Artifact sets that can many common binary/large files from version to version will then be able to detect that it already have have this file in the LFS storage and do not have to fetch/push it again.
+ Artifact sets that can handle many common binary/large files from version to version will then be able to detect that it already has this file in the LFS storage and does not have to fetch/push it again. Committable suggestion
Suggested change
|
||||||
- You can download all tags without checkout and then you can search for meta-data in the annotated tags without suffering large data transfer and storage in order to clean. | ||||||
|
||||||
### Promotions | ||||||
|
||||||
There are genrally default two ways to you can do promotions. | ||||||
Building new artifacts for the release is like a new artifact using the above patterns, which can either be a new or appended artifacts. | ||||||
|
||||||
Promotion decision should also be seen in connection related to pruning of tag which is not valid of any interest anymore. It should be simple and easy to prune without fear of deleting tags that should not be deleted | ||||||
|
||||||
#### Using different repository | ||||||
|
||||||
This way is like promotion in normal artifact managemnet systems, where you promote to from one project/repository to another. You basically download the tag from the original repository and then push the tag to promotion reposity. This way you can control access and keep different URL's for candidates and releases. | ||||||
|
||||||
#### Using same repository | ||||||
This way requires you to create a tag using a release tag pattern. The tag can either be a new unrelated tag or it can be append on top if a release candidate tag. | ||||||
|
||||||
|
||||||
This way requires you to create a tag using a release tag pattern. The tag can either be a new unrelated tag or it can be append on top if a release candidate tag. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Correct the verb form "be append" to "be appended". - The tag can either be a new unrelated tag or it can be append on top if a release candidate tag.
+ The tag can either be a new unrelated tag or it can be appended on top of a release candidate tag. Committable suggestion
Suggested change
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Correct the term "rational" to "rationale".
Committable suggestion