[Feature] Commit-based Change History

[skoropadas]

Description

An idea has emerged to automatically gather and display changes that have occurred in a project based on changes in the repository.

If your project uses the commit format adopted by Angular, then NgDoc could automatically gather and display such changes on certain pages based on the scope.

Proposed solution

This function should be optional by default and only enabled after setup:

• There should be an option to set a scope for each guide that corresponds to the scope in the commit. Based on this scope, NgDoc will gather and display changes for each page. By default, the current guide route can be used as a scope.
• There should be an option to configure the range of versions from which changes will be gathered, for example, for the last 5 minor versions, the latest major version, etc.
• It should be possible to configure the types of commits that should be taken when displaying changes, for example, only gathering changes for the types of docs, feat, fix.
• In the sidebar, an icon "New"/"Update" must be displayed to inform the user that related scope to the guide has been created, changed or updated.
• add option to avoid adding changes to the change log, it can be [skip ng-doc] tag in the body of the commit

Issues to address before implementation:

• Should the list of changes for the API be displayed? If so, based on what criteria? One option could be to use the declaration name as a scope to match the commit change with the API page.

Alternatives considered

There is also an option to make the display of changes more flexible on any required page. For example, NgDocActions could be used to pass a list of scopes for which the list of changes needs to be rendered. In this case, it can be displayed anywhere on the page, and the issue with the API will disappear on its own because the user can decide which scopes to render for the page. However, this will add additional load on the user and require them to add such a call to every page.

[skoropadas]

If you have any thoughts about this feature please share!

[semicolin]

My team does not use the Angular commit format, but I am interested in some kind of documentation history/versioning so users who are on an older version can see the documentation that matches their version.

[skoropadas]

@semicolin This ticket is more about displaying the history of changes for specific pages. For example, if a page is dedicated to a button and its functionality, theoretically, it could automatically generate and display the history of the button's recent changes. I believe such a feature could be convenient.

Regarding versioning and documentation for different versions of the library/project, I've considered this. It's not entirely NgDoc's responsibility, and I think the optimal solution would be to create and deploy multiple Angular applications.

For instance, let's say you have a library. If you maintain multiple versions, you'll likely have branches like 1.x.x, 2.x.x, and so on in your repository to facilitate bug fixes and updates for them. Correspondingly, you'll have pipelines for releasing the library and deploying its documentation.

In theory, in your pipeline, you could publish applications on specific routes using a script or any other method based on the major version. For example, my-doc.com/v1 could point to the application from the 1.x.x branch, and my-doc.com/v2 to the application from the 2.x.x branch. In the demo application itself, you could add something like a dropdown list to switch between versions. I think this solution is the simplest; it wouldn't require extensive support and should work with your server's standard routing.

Of course, there could also be an example involving micro-frontends, but I believe it would be more complex to implement and would require additional actions when new versions of the application are released. Therefore, I would prefer the option of having multiple applications on different routes.