Skip to content
Snippets Groups Projects

20240701_faq.md: Comment top level parts that should not be displayed

Merged 20240701_faq.md: Comment top level parts that should not be displayed
anlambert/swh-faq:comment-parts-not-to-display into main
1 unresolved thread
Merged Antoine Lambert requested to merge anlambert/swh-faq:comment-parts-not-to-display into main
1 unresolved thread
Compare
and
2 files
+ 34
− 19
Compare changes
  • Side-by-side
  • Inline
Files
2
20240701_faq.md
+ 29
− 17
<!---
This is commented because the FAQ page on SWH WordPress website is
dynamically generated from this markdown document and this should
not be displayed.
After each document update in this git repository, the FAQ page is
automatically updated on the WordPress website.
---
tags: documentation, ambassadors
---
Why this new version?
Slight changes have to be made.
Why this new version?
Slight changes have to be made.
See questions in:
See questions in:
https://hedgedoc.softwareheritage.org/6hFGAHdUTY2wWKr5OqwzkQ?both#
# FAQ Software Heritage (website)
## 1. General
--->
## 1. General
### 1.1 What is Software Heritage?
@@ -28,7 +40,7 @@ For more information about the Software Heritage [mission](https://www.softwareh
### 1.2 What is the Software Heritage archive?
The Software Heritage archive is the largest public collection of source code in existence. Visit the archive on https://archive.softwareheritage.org.
The Software Heritage archive is the largest public collection of source code in existence. Visit the archive on https://archive.softwareheritage.org.
### 1.3 What is the size of the archive?
The archive is growing over time as we crawl new source code from software projects and development forges. You can see live counters of the archive contents, as well as a breakdown by crawled origins, on https://archive.softwareheritage.org.
@@ -62,7 +74,7 @@ Here is an excerpt of this list:
### 2.2 If my code is on GitHub/GitLab/Bitbucket, is it already archived in Software Heritage?
It might be, as we crawl these and other popular forges regularly.
It might be, as we crawl these and other popular forges regularly.
Search for your code repository on https://archive.softwareheritage.org/browse/search/.
<details>
@@ -73,7 +85,7 @@ If it is not there yet, or if the latest snapshot is not the most recent state o
https://archive.softwareheritage.org/save/ or by clicking on the "Save again" button in the browse view.
![](https://hedgedoc.softwareheritage.org/uploads/upload_f927d52a90509ceae1f6bd595ace41a2.png)
A [GitHub action](https://github.com/marketplace/actions/save-to-software-heritage) is available to automatically push a save code now request. Here is an [example](https://github.com/patrickfuchs/buildH/blob/master/.github/workflows/archive-to-software-heritage.yml) of this action configured to run each time a new release is issued.
You can also use the [browser extension](https://www.softwareheritage.org/2022/08/02/updateswh-browser-extension/).
@@ -91,7 +103,7 @@ We do not inspect or filter the source code, and archive anything that we can ge
<summary> Expand for details </summary>
<br>
The reason for this approach is because the value of software source code cannot be known in advance. When a project starts, one cannot predict whether it will become a key software component or not. For example, when [Rasmus Lerdorf](https://fr.wikipedia.org/wiki/Rasmus_Lerdorf) released [the first version on PHP back in 1995](https://groups.google.com/g/comp.infosystems.www.authoring.cgi/c/PyJ25gZ6z7A/m/M9FkTUVDfcwJ), who could have predicted that it would become one of the most popular tools for the Web.
The reason for this approach is because the value of software source code cannot be known in advance. When a project starts, one cannot predict whether it will become a key software component or not. For example, when [Rasmus Lerdorf](https://fr.wikipedia.org/wiki/Rasmus_Lerdorf) released [the first version on PHP back in 1995](https://groups.google.com/g/comp.infosystems.www.authoring.cgi/c/PyJ25gZ6z7A/m/M9FkTUVDfcwJ), who could have predicted that it would become one of the most popular tools for the Web.
<figure>
<img src="https://imgs.xkcd.com/comics/dependency.png">
@@ -101,7 +113,7 @@ XKCD Comics https://xkcd.com/2347/ (CC BY-NC 2.5)
</figcaption>
</figure>
And it also happens that [very precious pieces of source code may be go unnoticed for decades](https://en.wikipedia.org/wiki/OpenSSL), until one day [some unexpected bug unveils that a big part of our digital infrastructure relies on them](https://en.wikipedia.org/wiki/Heartbleed).
And it also happens that [very precious pieces of source code may be go unnoticed for decades](https://en.wikipedia.org/wiki/OpenSSL), until one day [some unexpected bug unveils that a big part of our digital infrastructure relies on them](https://en.wikipedia.org/wiki/Heartbleed).
</details>
@@ -120,8 +132,8 @@ Our core mission is to preserve source code, because it is human readable and co
### 2.7 I can't find all my "releases" in a git repository in Software Heritage, what should I do?
Do not worry, your repository has been saved in full.
What you are witnessing is just a terminological difference between what
Do not worry, your repository has been saved in full.
What you are witnessing is just a terminological difference between what
platforms like GitHub calls "releases" (any non annotated git tag) and what we call "releases" (a node in the Merkle tree, which corresponds to a git annotated tag). This is a common issue, as you can see for example in [this discussion thread](https://stackoverflow.com/questions/11514075/what-is-the-difference-between-an-annotated-and-unannotated-tag).
<details>
@@ -223,7 +235,7 @@ Notice that the Permalinks tab offers a plurality of options to pick a SWHID (yo
![](https://annex.softwareheritage.org/public/tutorials/getswhid_snippet.gif)
</details>
### 3.4 Which type of SWHID should I use in my article/documentation?
### 3.4 Which type of SWHID should I use in my article/documentation?
It really depends on your use case, but as a general suggestion we recommend to take *the full SWHID of a directory (with the contextual information)*.
@@ -234,7 +246,7 @@ It really depends on your use case, but as a general suggestion we recommend to
When writing a research article, a blog post or technical documentation, one may face some tension between the need to provide the maximum amount of information, using the full SWHID, or keeping the reference short (for example due to page limitations).
Here is the recommended best practice to address this issue:
Here is the recommended best practice to address this issue:
1) get the full SWHID for the 'directory' containing the version of the code you want to reference. Here is an example of such a full SWHID:
`swh:1:dir:013573086777370b558b1a9ecb6d0dca9bb8ea18;origin=https://gitlab.com/lemta-rheosol/craft-virtual-dma;visit=swh:1:snp:ef1a939275f05b667e189afbeed5fd59cca51c9d;anchor=swh:1:rev:ad74f6a7f73c7906f9b36ee28dd006231f42552e`
@@ -244,7 +256,7 @@ This effect can be achieved as follows in LaTeX:
```\href{https://archive.softwareheritage.org/swh:1:dir:013573086777370b558b1a9ecb6d0dca9bb8ea18;origin=https://gitlab.com/lemta-rheosol/craft-virtual-dma;visit=swh:1:snp:ef1a939275f05b667e189afbeed5fd59cca51c9d;anchor=swh:1:rev:ad74f6a7f73c7906f9b36ee28dd006231f42552e/}{swh:1:dir:013573086777370b558b1a9ecb6d0dca9bb8ea18}```
or in Markdown:
or in Markdown:
```[swh:1:dir:013573086777370b558b1a9ecb6d0dca9bb8ea18](https://archive.softwareheritage.org/swh:1:dir:013573086777370b558b1a9ecb6d0dca9bb8ea18;origin=https://gitlab.com/lemta-rheosol/craft-virtual-dma;visit=swh:1:snp:ef1a939275f05b667e189afbeed5fd59cca51c9d;anchor=swh:1:rev:ad74f6a7f73c7906f9b36ee28dd006231f42552e/)```
@@ -257,7 +269,7 @@ In the digital version *the clickable link* uses *the full SWHID* to let the rea
If your code (or the latest version of it) is not yet in the archive, you need first to trigger its archival. This can be done with a ["Save Code Now"](https://save.softwareheritage.org) request, or via the deposit API.
Once a Save Code Now request is issued, the ingestion of the code is usually completed in a few minutes, depending on the size of the repository. Once it's done, the status of the save request is updated and you can get the SWHID as shown before.
Once a Save Code Now request is issued, the ingestion of the code is usually completed in a few minutes, depending on the size of the repository. Once it's done, the status of the save request is updated and you can get the SWHID as shown before.
When a deposit is submitted, the ingestion is also usually completed in a few minutes and the SWHID is accessible through the SWORD status response.
@@ -284,7 +296,7 @@ Please do not clone a full repository directly from Software Heritage: it is an
<summary> Expand for details </summary>
<br>
Software Heritage stores all the software artifacts in a massive shared [Merkle tree](https://en.wikipedia.org/wiki/Merkle_tree), so that exporting (a specific version of) an archived respository implies traversing the graph to get all the relevant contents and packaging them up for your consumption. This operation is much more expensive than downloading an existing tar file or cloning a repository from a forge.
Software Heritage stores all the software artifacts in a massive shared [Merkle tree](https://en.wikipedia.org/wiki/Merkle_tree), so that exporting (a specific version of) an archived respository implies traversing the graph to get all the relevant contents and packaging them up for your consumption. This operation is much more expensive than downloading an existing tar file or cloning a repository from a forge.
If really Software Heritage is your last resort, and you cannot find the source code of interest elsewhere, we recommend that you download only the version of interest for you, using the "*directory*" option of the Download button that you find when you browse the archive.
@@ -360,7 +372,7 @@ Last but not least, [Software Heritage indexes](https://www.softwareheritage.org
<figure>
<img src="https://hedgedoc.softwareheritage.org/uploads/upload_ef853cffeee220220c6e12a7ba0c40db.png">
<figcaption>
Credit: Gruenpeter M. and Thornton K. (2018) Pathways for Discovery of Free Software (slide deck from LibrePlanet 2018). https://en.wikipedia.org/wiki/File:Pathways-discovery-free.pdf
</figcaption>
</figure>