paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity
Files
bbdeb50ba7671a0f2bd93d5800fc36760cfaea9d
backstage/packages/techdocs-common/CHANGELOG.md
T
github-actions[bot] 5a64fe7ea5 Version Packages
2021-06-24 09:58:38 +00:00

19 KiB
Raw Blame History

@backstage/techdocs-common

0.6.5

Patch Changes

  • c17c0fcf9: Adding additional checks on tech docs to prevent folder traversal via mkdocs.yml docs_dir value.
  • Updated dependencies
    • @backstage/catalog-model@0.8.4

0.6.4

Patch Changes

  • aad98c544: Fixes multiple XSS and sanitization bypass vulnerabilities in TechDocs.
  • 090594755: Support parsing mkdocs.yml files that are using custom yaml tags like !!python/name:materialx.emoji.twemoji.
  • Updated dependencies [ebe802bc4]
  • Updated dependencies [49d7ec169]
    • @backstage/catalog-model@0.8.1
    • @backstage/integration@0.5.5

0.6.3

Patch Changes

  • 8cefadca0: Adding validation to mkdocs.yml parsing to prevent directory tree traversing
  • Updated dependencies [0fd4ea443]
  • Updated dependencies [add62a455]
  • Updated dependencies [704875e26]
    • @backstage/integration@0.5.4
    • @backstage/catalog-model@0.8.0

0.6.2

Patch Changes

  • 65e6c4541: Remove circular dependencies
  • Updated dependencies [f7f7783a3]
  • Updated dependencies [c7dad9218]
  • Updated dependencies [65e6c4541]
  • Updated dependencies [68fdbf014]
  • Updated dependencies [5001de908]
    • @backstage/catalog-model@0.7.10
    • @backstage/backend-common@0.8.1
    • @backstage/integration@0.5.3

0.6.1

Patch Changes

  • e04f1ccfb: Fixed a bug that prevented loading static assets from GCS, S3, Azure, and OpenStackSwift whose keys contain spaces or other special characters.
  • Updated dependencies [22fd8ce2a]
  • Updated dependencies [10c008a3a]
  • Updated dependencies [f9fb4a205]
  • Updated dependencies [16be1d093]
    • @backstage/backend-common@0.8.0
    • @backstage/catalog-model@0.7.9

0.6.0

Minor Changes

  • e0bfd3d44: Migrate the package to use the ContainerRunner interface instead of runDockerContainer(…). It also no longer provides the ContainerRunner as an input to the GeneratorBase#run(…) function, but expects it as a constructor parameter instead.

    If you use the TechdocsGenerator you need to update the usage:

    + const containerRunner = new DockerContainerRunner({ dockerClient });

- const generator = new TechdocsGenerator(logger, config);
+ const techdocsGenerator = new TechdocsGenerator({
+   logger,
+   containerRunner,
+   config,
+ });

  await this.generator.run({
    inputDir: preparedDir,
    outputDir,
-   dockerClient: this.dockerClient,
    parsedLocationAnnotation,
    etag: newEtag,
  });

Patch Changes

  • e9e56b01a: Adding optional config to enable S3-like API for tech-docs using s3ForcePathStyle option. This allows providers like LocalStack, Minio and Wasabi (+possibly others) to be used to host tech docs.
  • Updated dependencies [e0bfd3d44]
  • Updated dependencies [38ca05168]
  • Updated dependencies [d8b81fd28]
    • @backstage/backend-common@0.7.0
    • @backstage/integration@0.5.2
    • @backstage/catalog-model@0.7.8
    • @backstage/config@0.1.5

0.5.1

Patch Changes

  • f4af06ebe: Gracefully handle HTTP request failures in download method of AzureBlobStorage publisher.

0.5.0

Minor Changes

  • bc9d62f4f: Move the sanity checks of the publisher configurations to a dedicated PublisherBase#getReadiness() method instead of throwing an error when doing Publisher.fromConfig(...). You should include the check when your backend to get early feedback about a potential misconfiguration:

      // packages/backend/src/plugins/techdocs.ts

  export default async function createPlugin({
    logger,
    config,
    discovery,
    reader,
  }: PluginEnvironment): Promise<Router> {
    // ...

    const publisher = await Publisher.fromConfig(config, {
      logger,
      discovery,
    })

+   // checks if the publisher is working and logs the result
+   await publisher.getReadiness();

    // Docker client (conditionally) used by the generators, based on techdocs.generators config.
    const dockerClient = new Docker();

    // ...
}

    If you want to crash your application on invalid configurations, you can throw an Error to preserve the old behavior. Please be aware that this is not the recommended for the use in a Backstage backend but might be helpful in CLI tools such as the techdocs-cli.

    const publisher = await Publisher.fromConfig(config, {
  logger,
  discovery,
});

const ready = await publisher.getReadiness();
if (!ready.isAvailable) {
  throw new Error('Invalid TechDocs publisher configuration');
}

Patch Changes

  • Updated dependencies [bb5055aee]
  • Updated dependencies [5d0740563]
    • @backstage/catalog-model@0.7.7

0.4.5

Patch Changes

  • 8686eb38c: Use errors from @backstage/errors

  • 424742dc1: Applies only if you use TechDocs local builder instead of building on CI/CD i.e. if techdocs.builder in your app-config.yaml is set to 'local'

    Improvements

    1. Do not check for updates in the repository if a check has been made in the last 60 seconds. This is to prevent the annoying check for update on every page switch or load.
    2. No need to maintain an in-memory etag storage, and use the one stored in techdocs_metadata.json file alongside generated docs.

    New feature

    1. You can now use a mix of basic and recommended setup i.e. techdocs.builder is 'local' but using an external cloud storage instead of local storage. Previously, in this setup, the docs would never get updated.

  • Updated dependencies [8686eb38c]

  • Updated dependencies [0434853a5]

  • Updated dependencies [8686eb38c]

    • @backstage/backend-common@0.6.0
    • @backstage/config@0.1.4

0.4.4

Patch Changes

  • d7245b733: Remove runDockerContainer, and start using the utility function provided by @backstage/backend-common
  • 0b42fff22: Make use of parseLocationReference/stringifyLocationReference
  • 2ef5bc7ea: Implement proper AWS Credentials precedence with assume-role and explicit credentials
  • aa095e469: OpenStack Swift publisher added for tech-docs.
  • bc46435f5: - Improve deprecation warning messaging in logs.
  • a501128db: Refactor log messaging to improve clarity
  • ca4a904f6: Add an optional configuration option for setting the url endpoint for AWS S3 publisher: techdocs.publisher.awsS3.endpoint
  • Updated dependencies [277644e09]
  • Updated dependencies [52f613030]
  • Updated dependencies [d7245b733]
  • Updated dependencies [0b42fff22]
  • Updated dependencies [905cbfc96]
  • Updated dependencies [761698831]
  • Updated dependencies [d4e77ec5f]
    • @backstage/integration@0.5.1
    • @backstage/backend-common@0.5.6
    • @backstage/catalog-model@0.7.4

0.4.3

Patch Changes

  • f43192207: remove usage of res.send() for res.json() and res.end() to ensure content types are more consistently application/json on backend responses and error cases
  • 61299519f: Remove read-store-upload loop when uploading S3 objects for TechDocs
  • Updated dependencies [12d8f27a6]
  • Updated dependencies [497859088]
  • Updated dependencies [8adb48df4]
    • @backstage/catalog-model@0.7.3
    • @backstage/backend-common@0.5.5

0.4.2

Patch Changes

  • 2499f6cde: Add support for assuming role in AWS integrations
  • 1e4ddd71d: Fix AWS, GCS and Azure publisher to work on Windows.
  • Updated dependencies [bad21a085]
  • Updated dependencies [a1f5e6545]
    • @backstage/catalog-model@0.7.2
    • @backstage/config@0.1.3

0.4.1

Patch Changes

  • fb28da212: Switched to using 'x-access-token' for authenticating Git over HTTPS towards GitHub.
  • 26e143e60: After TechDocs generate step, insert build timestamp to techdocs_metadata.json
  • c6655413d: Improved error reporting in AzureBlobStorage to surface errors when fetching metadata and uploading files fails.
  • 44414239f: Pass user and group ID when invoking docker container. When TechDocs invokes Docker, docker could be run as a root user which results in generation of files by applications run by non-root user (e.g. TechDocs) will not have access to modify. This PR passes in current user and group ID to docker so that the file permissions of the generated files and folders are correct.
  • b0a41c707: Add etag of the prepared file tree to techdocs_metadata.json in the storage
  • Updated dependencies [16fb1d03a]
  • Updated dependencies [491f3a0ec]
  • Updated dependencies [491f3a0ec]
  • Updated dependencies [434b4e81a]
  • Updated dependencies [fb28da212]
    • @backstage/backend-common@0.5.4
    • @backstage/integration@0.5.0

0.4.0

Minor Changes

Patch Changes

0.3.7

Patch Changes

  • c777df180: 1. Added option to use Azure Blob Storage as a choice to store the static generated files for TechDocs.
  • e44925723: techdocs.requestUrl and techdocs.storageUrl are now optional configs and the discovery API will be used to get the URL where techdocs plugin is hosted.
  • f0320190d: dir preparer will use URL Reader in its implementation.
  • Updated dependencies [c4abcdb60]
  • Updated dependencies [2430ee7c2]
  • Updated dependencies [6e612ce25]
  • Updated dependencies [025e122c3]
  • Updated dependencies [064c513e1]
  • Updated dependencies [7881f2117]
  • Updated dependencies [3149bfe63]
  • Updated dependencies [2e62aea6f]
  • Updated dependencies [11cb5ef94]
    • @backstage/integration@0.3.2
    • @backstage/backend-common@0.5.2
    • @backstage/catalog-model@0.7.1

0.3.6

Patch Changes

  • 9dd057662: Upgrade git-url-parse to v11.4.4 which fixes parsing an Azure DevOps branch ref.
  • db2328c88: Add rate limiter for concurrent execution of file uploads in AWS and Google publishers
  • Updated dependencies [26a3a6cf0]
  • Updated dependencies [664dd08c9]
  • Updated dependencies [6800da78d]
  • Updated dependencies [9dd057662]
    • @backstage/backend-common@0.5.1
    • @backstage/integration@0.3.1

0.3.5

Patch Changes

  • 53c9c51f2: TechDocs backend now streams files through from Google Cloud Storage to the browser, improving memory usage.

  • a5e27d5c1: Create type for TechDocsMetadata (#3716)

    This change introduces a new type (TechDocsMetadata) in packages/techdocs-common. This type is then introduced in the endpoint response in techdocs-backend and in the api interface in techdocs (frontend).

  • Updated dependencies [def2307f3]

  • Updated dependencies [0b135e7e0]

  • Updated dependencies [294a70cab]

  • Updated dependencies [fa8ba330a]

  • Updated dependencies [0ea032763]

  • Updated dependencies [5345a1f98]

  • Updated dependencies [ed6baab66]

  • Updated dependencies [09a370426]

  • Updated dependencies [a93f42213]

    • @backstage/catalog-model@0.7.0
    • @backstage/backend-common@0.5.0
    • @backstage/integration@0.3.0

0.3.4

Patch Changes

  • a594a7257: @backstage/techdocs-common can now be imported in an environment without @backstage/plugin-techdocs-backend being installed.

0.3.3

Patch Changes

  • 68ad5af51: Improve techdocs-common Generator API for it to be used by techdocs-cli. TechDocs generator.run function now takes an input AND an output directory. Most probably you use techdocs-common via plugin-techdocs-backend, and so there is no breaking change for you. But if you use techdocs-common separately, you need to create an output directory and pass into the generator.

  • 371f67ecd: fix to-string breakage of binary files

  • f1e74777a: Fix bug where binary files (png, etc.) could not load when using AWS or GCS publisher.

  • dbe4450c3: Google Cloud authentication in TechDocs has been improved.

    1. techdocs.publisher.googleGcs.credentials is now optional. If it is missing, GOOGLE_APPLICATION_CREDENTIALS environment variable (and some other methods) will be used to authenticate. Read more here https://cloud.google.com/docs/authentication/production

    2. techdocs.publisher.googleGcs.projectId is no longer used. You can remove it from your app-config.yaml.

  • 5826d0973: AWS SDK version bump for TechDocs.

  • b3b9445df: AWS S3 authentication in TechDocs has been improved.

    1. techdocs.publisher.awsS3.bucketName is now the only required config. techdocs.publisher.awsS3.credentials and techdocs.publisher.awsS3.region are optional.

    2. If techdocs.publisher.awsS3.credentials and techdocs.publisher.awsS3.region are missing, the AWS environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_REGION will be used. There are more better ways of setting up AWS authentication. Read the guide at https://backstage.io/docs/features/techdocs/using-cloud-storage

  • Updated dependencies [466354aaa]

  • Updated dependencies [f3b064e1c]

  • Updated dependencies [abbee6fff]

  • Updated dependencies [147fadcb9]

    • @backstage/integration@0.2.0
    • @backstage/catalog-model@0.6.1
    • @backstage/backend-common@0.4.3

0.3.2

Patch Changes

  • 7ec525481: 1. Added option to use AWS S3 as a choice to store the static generated files for TechDocs.
  • f8ba88ded: Fix for integration.github.apiBaseUrl configuration not properly overriding apiBaseUrl used by techdocs
  • 00042e73c: Moving the Git actions to isomorphic-git instead of the node binding version of nodegit
  • Updated dependencies [5ecd50f8a]
  • Updated dependencies [00042e73c]
  • Updated dependencies [0829ff126]
  • Updated dependencies [036a84373]
    • @backstage/backend-common@0.4.2
    • @backstage/integration@0.1.5

0.3.1

Patch Changes

  • 8804e8981: Using @backstage/integration package for GitHub/GitLab/Azure tokens and request options.

    Most probably you do not have to make any changes in the app because of this change. However, if you are using the DirectoryPreparer or CommonGitPreparer exported by @backstage/techdocs-common package, you now need to add pass in a config (from @backstage/config) instance as argument.

    <!-- Before -->
    const directoryPreparer = new DirectoryPreparer(logger);
    const commonGitPreparer = new CommonGitPreparer(logger);
<!-- Now -->
    const directoryPreparer = new DirectoryPreparer(config, logger);
    const commonGitPreparer = new CommonGitPreparer(config, logger);

0.3.0

Minor Changes

  • a8573e53b: techdocs-backend: Simplified file, removing individual preparers and generators. techdocs-backend: UrlReader is now available to use in preparers.

    In your Backstage app, packages/backend/plugins/techdocs.ts file has now been simplified, to remove registering individual preparers and generators.

    Please update the file when upgrading the version of @backstage/plugin-techdocs-backend package.

    const preparers = await Preparers.fromConfig(config, {
  logger,
  reader,
});

const generators = await Generators.fromConfig(config, {
  logger,
});

const publisher = await Publisher.fromConfig(config, {
  logger,
  discovery,
});

    You should be able to remove unnecessary imports, and just do

    import {
  createRouter,
  Preparers,
  Generators,
  Publisher,
} from '@backstage/plugin-techdocs-backend';

0.2.0

Minor Changes

  • dae4f3983: Breaking changes

    1. Added option to use Google Cloud Storage as a choice to store the static generated files for TechDocs. It can be configured using techdocs.publisher.type option in app-config.yaml. Step-by-step guide to configure GCS is available here https://backstage.io/docs/features/techdocs/using-cloud-storage Set techdocs.publisher.type to 'local' if you want to continue using local filesystem to store TechDocs files.

    2. techdocs.builder is now required and can be set to 'local' or 'external'. (Set it to 'local' for now, since CI/CD build workflow for TechDocs will be available soon (in few weeks)). If builder is set to 'local' and you open a TechDocs page, techdocs-backend will try to generate the docs, publish to storage and show the generated docs afterwords. If builder is set to 'external', techdocs-backend will only fetch the docs and will NOT try to generate and publish. In this case of 'external', we assume that docs are being built in the CI/CD pipeline of the repository. TechDocs will not assume a default value for techdocs.builder. It is better to explicitly define it in the app-config.yaml.

    3. When configuring TechDocs in your backend, there is a difference in how a new publisher is created.

    ---  const publisher = new LocalPublish(logger, discovery);
+++  const publisher = Publisher.fromConfig(config, logger, discovery);

    Based on the config techdocs.publisher.type, the publisher could be either Local publisher or Google Cloud Storage publisher.

    1. techdocs.storageUrl is now a required config. Should be http://localhost:7000/api/techdocs/static/docs in most setups.

    2. Parts of @backstage/plugin-techdocs-backend have been moved to a new package @backstage/techdocs-common to generate docs. Also to publish docs to-and-fro between TechDocs and a storage (either local or external). However, a Backstage app does NOT need to import the techdocs-common package - app should only import @backstage/plugin-techdocs and @backstage/plugin-techdocs-backend.

    Patch changes

    1. See all of TechDocs config options and its documentation https://backstage.io/docs/features/techdocs/configuration

    2. Logic about serving static files and metadata retrieval have been abstracted away from the router in techdocs-backend to the instance of publisher.

    3. Removed Material UI Spinner from TechDocs header. Spinners cause unnecessary UX distraction. Case 1 (when docs are built and are to be served): Spinners appear for a split second before the name of site shows up. This unnecessarily distracts eyes because spinners increase the size of the Header. A dot (.) would do fine. Definitely more can be done. Case 2 (when docs are being generated): There is already a linear progress bar (which is recommended in Storybook).

Patch Changes

  • Updated dependencies [c911061b7]
  • Updated dependencies [1d1c2860f]
  • Updated dependencies [0e6298f7e]
  • Updated dependencies [4eafdec4a]
  • Updated dependencies [ac3560b42]
    • @backstage/catalog-model@0.6.0
    • @backstage/backend-common@0.4.1
Reference in New Issue View Git Blame Copy Permalink