paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 25 Packages Projects Releases Wiki Activity

add git feedback link: update FAQ and unit testing

Browse Source 
Signed-off-by: Chongyang Adrian, Ke <ftt.adrian.ke@grabtaxi.com>
This commit is contained in:
Chongyang Adrian, Ke
2021-04-20 13:32:34 +08:00
parent ac6025f63a
commit 2b440c0605
3 changed files with 45 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/techdocs-eight-camels-hear.md
+1 -2
View File
@@ -4,5 +4,4 @@
Add feedback link icon in Techdocs Reader that directs to Gitlab or Github repo issue page with prefilled title and source link.
For link to appear, requires repo_url and edit_uri to be filled in mkdocs.yml, as per https://www.mkdocs.org/user-guide/configuration. edit_uri will need to be specified for self-hosted Gitlab/Github with different hostnames.
Gitlab or Github detection checks for 'gitlab' or 'github' in hostname of source in repo_url;
additionally 'techdocs.feedback.gitlab' and '.github' in app config can be used to specify hostnames that should be recognised as the respective Git hosting for the feedback link.
To identify issue URL format as Github or Gitlab, the hostname of source in repo_url is checked if it contains 'gitlab' or 'github'. Alternately this is determined by matching to 'host' values from 'integrations' in app-config.yaml.
docs/features/techdocs/FAQ.md
+12
View File
@@ -45,3 +45,15 @@ metadata annotation is used in the build process of TechDocs. But when
annotation should still be present in entity descriptor file (e.g.
`catalog-info.yaml`) for Backstage to know that TechDocs is enabled for the
entity.
#### Is it possible for users to suggest changes or provide feedback on a TechDocs page?
This is supported for TechDocs sites whose source code is hosted in either
GitHub or GitLab. In order to add "edit this page" and "leave feedback" buttons
on a TechDocs page, be sure that you have `repo_url` and `edit_uri` values in
your `mkdocs.yml` files per
[MkDocs instructions](https://www.mkdocs.org/user-guide/configuration).
If the hostname of your source code hosting URL does not include 'github' or
'gitlab', an `integrations` entry in your `app-config.yaml` pointed at your
source code provider is also needed (only the `host` key is necessary).
plugins/techdocs/src/reader/transformers/addGitFeedbackLink.test.ts
+32 -5
View File
@@ -18,8 +18,10 @@ import { createTestShadowDom } from '../../test-utils';
import { addGitFeedbackLink } from './addGitFeedbackLink';
const configApi = {
getOptionalString: function getOptionalString(key: string) {
return key === 'gitlab' ? 'gitlab.com' : 'github.com';
getConfigArray: function getConfigArray(key: string) {
return key === 'integrations.github'
? [{ data: { host: 'self-hosted-git-hub-provider.com' } }]
: [];
},
};
@@ -80,7 +82,7 @@ describe('addGitFeedbackLink', () => {
<!DOCTYPE html>
<html>
<article class="md-content__inner">
<h1 id="conveyor-pipelines">Conveyor Pipelines<a class="headerlink" href="http://headerlink.com">¶</a></h1>
<h1>HeaderText<a class="headerlink" href="http://headerlink.com">¶</a></h1>
</article>
</html>
`,
@@ -99,8 +101,8 @@ describe('addGitFeedbackLink', () => {
<!DOCTYPE html>
<html>
<article class="md-content__inner">
<h1 id="conveyor-pipelines">Conveyor Pipelines<a class="headerlink" href="http://headerlink.com">¶</a></h1>
<a href="https://not-a-git-provider.com/reponame/username/docs/TestDoc.md"/>
<h1>HeaderText<a class="headerlink" href="http://headerlink.com">¶</a></h1>
<a title="Edit this page" href="https://not-a-git-provider.com/reponame/username/docs/TestDoc.md"/>
</article>
</html>
`,
@@ -112,4 +114,29 @@ describe('addGitFeedbackLink', () => {
expect(shadowDom.querySelector('#git-feedback-link')).toBeFalsy();
});
it('adds a feedback link when a Gitlab or Github source edit link is not available but hostname matches an integrations host', () => {
const shadowDom = createTestShadowDom(
`
<!DOCTYPE html>
<html>
<article class="md-content__inner">
<h1>HeaderText<a class="headerlink" href="http://headerlink.com">¶</a></h1>
<a title="Edit this page" href="https://self-hosted-git-hub-provider.com/reponame/username/docs/TestDoc.md"/>
</article>
</html>
`,
{
preTransformers: [addGitFeedbackLink(configApi)],
postTransformers: [],
},
);
expect(shadowDom.querySelector('#git-feedback-link')).toBeTruthy();
expect(
(shadowDom.querySelector('#git-feedback-link') as HTMLLinkElement)!.href,
).toEqual(
'https://self-hosted-git-hub-provider.com/reponame/username/issues/new?title=Documentation%20Feedback%3A%20HeaderText&body=Page%20source%3A%0Ahttps%3A%2F%2Fself-hosted-git-hub-provider.com%2Freponame%2Fusername%2Fdocs%2FTestDoc.md%0A%0AFeedback%3A',
);
});
});