-
Notifications
You must be signed in to change notification settings - Fork 1.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #5320 from newrelic/deleted-files
chore:create doc that coveres history and deleted docs
- Loading branch information
Showing
3 changed files
with
92 additions
and
36 deletions.
There are no files selected for viewing
90 changes: 90 additions & 0 deletions
90
src/content/docs/style-guide/writing-docs/writer-workflow/github-history.mdx
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 |
---|---|---|
@@ -0,0 +1,90 @@ | ||
--- | ||
title: GitHub history and deleted files | ||
topics: | ||
- Tech writer style guide | ||
- How to use GitHub | ||
redirects: | ||
- /docs/style-guide/writer-workflow/github-intro | ||
--- | ||
|
||
GitHub's version control features allow us to see the complete history of a doc, access a doc at any point in time, and find deleted docs without manual backups. | ||
|
||
## Check the edit history of a doc or file [#doc-history] | ||
Use any of these options to check or "diff" the history of a file. | ||
|
||
**Option 1: GitHub history tab** | ||
1. Navigate to the doc on the doc site and click **Edit page** in the right nav. | ||
2. Click **History** in the top right corner of the doc. | ||
|
||
**Option 2: githistory.xy** | ||
1. Navigate to your specific file on GitHub.com: | ||
``` | ||
https://github.com/newrelic/docs-website/blob/develop/src/content/docs/browser/new-relic-browser/browser-agent-spa-api/add-page-action.mdx | ||
``` | ||
2. In the url, replace `github.com` with `github.githistory.xyz`: | ||
``` | ||
https://github.githistory.xyz/newrelic/docs-website/blob/develop/src/content/docs/browser/new-relic-browser/browser-agent-spa-api/add-page-action.mdx | ||
``` | ||
|
||
3. It will take you to a site which presents the visual history of that specific file. You can view changes by clicking through the commit history at the top of your page. | ||
|
||
**Option 3: Git blame** | ||
|
||
Follow [GitHub's documentation](https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/tracking-changes-in-a-file). | ||
|
||
Alternatively, you can use the following command in your terminal: | ||
``` | ||
git log --follow "**/file_name_here.mdx" | ||
``` | ||
This will output the commit history of that file. By default, it only shows the first few commits. You can scroll by pressing Return multiple times. | ||
|
||
For example, to find the commit history for `vmware-vsphere-monitoring-integration.mdx`, I would run: | ||
``` | ||
git log --follow "**/vmware-vsphere-monitoring-integration.mdx" | ||
``` | ||
## Docs site history before October 2021 [#archived-version] | ||
|
||
We had a large site restructure in October 2021 which lost most of the file history for our docs. You can find an archived version of our site pre-rework in the [pre-IA-2021](https://github.com/newrelic/docs-website/tree/pre-IA-2021) branch. By navigating the pre-rework version of our repo, you can find file history and more. | ||
|
||
## How to find deleted files [#deleted-files] | ||
|
||
There are multiple ways to find deleted files. These are roughly ordered by complexity: | ||
|
||
<CollapserGroup> | ||
<Collapser | ||
className="freq-link" | ||
id="pr" | ||
title="Finding the deletion PR" | ||
> | ||
|
||
The easiest way to find a deleted file is to find the pull request that deleted it. There are multiple ways to accomplish this; here are some ideas: | ||
|
||
1. Use GitHub's search feature to search for relevant keywords. You can filter search results to only include PRs. | ||
2. If you have a rough idea of when the doc was deleted, you could try finding the pull request in the pull request tab. This list has thousands of PRs, so this may take some time. | ||
3. Lots of docs are deleted because of a Jira ticket. Search Jira for the ticket, where you will find the rough time the doc was deleted and hopefully a link to the PR itself. | ||
4. Ask in #doc_talk! | ||
|
||
</Collapser> | ||
<Collapser | ||
className="freq-link" | ||
id="releases" | ||
title="Search through release PRs" | ||
> | ||
|
||
By searching through release PRs, you can eventually find a branch created before the doc was deleted. You can find a list of release PRs in the [GitHub PR tab](https://github.com/newrelic/docs-we.bsite/pulls?q=is%3Apr+release+is%3Aclosed). | ||
|
||
A few tips: | ||
- Search by intervals of a month first. Once you find a branch that contains the doc, you can scope down to a week and then to a day. By decreasing the scope, you will eventually find the deleted doc in it's exact state before deletion. | ||
- To access the branch a PR comes from, go to that pull request's page and click on the branch name underneath the title and PR number. | ||
|
||
</Collapser> | ||
<Collapser | ||
className="freq-link" | ||
id="git-log" | ||
title="Use git log" | ||
> | ||
|
||
The most powerful and realiable way to find deleted files is to use git log. See [stackoverflow](https://stackoverflow.com/questions/7203515/how-to-find-a-deleted-file-in-the-project-commit-history/7203551#7203551) for more details. | ||
|
||
</Collapser> | ||
</CollapserGroup> |
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