We would love to use this addon, however since we have a number of repositories (20+) it's not feasible to write and maintain 20+ .md files. This is a feature request to be able to select a master repository from which the CONTRIBUTING.md file is fetched.
Thank you for letting me know. I have a feature branch on this repo that allows for imports. When that is merged, you will be able to create a repo with the guidelines for all your other repos and just import specific guidelines files when you need to. I'll try to find some time to finish it off.
Cool, thanks!
Has there been any update on this. Just curious. We use Confluence as well. So might go the route of hosting the guidelines on a Confluence page. It would be nice to link to the confluence page from the PR too though.
Hi @sudr-mg,
Unfortunately, I have not had much of a chance to work on prguidelines recently (it's a side-project and not part of my job, so I have to find the time during weekends and evenings).
Fortunately, we have a shipit coming up next week. I think I'll try to push this feature out for this shipit. I'll update this ticket next week.
@rw_richard @sudr-mg I have good news. I just merged and deployed the ability to import guidelines. So now, you should be able to start your CONTRIBUTING.md file with an import statement that will be able to pull up guidelines from other files in other repositories. This will allow you to create a repository in your team that stores all the common guidelines. The syntax for this import is pretty primitive and I'll try to work on that later, but the current solution should help solve your problems. Let me illustrate how this will work with an example:
For this to work, you will have to create markdown files in your "guidelines" repository that follow the usual prguidelines format. Then, for any repository that wants to import any of these files, you can start the CONTRIBUTING.md file in that repository with
<!-- import api/1.0/repositories/<team-name>/<guidelines-repo-name>/src/<hash-of-commit-from-guidelines-repo>/<filename.md> -->
The imported guideline could further import from elsewhere and prguidelines will follow the import chain. The imports will time out in 5 seconds.
I recommend using specific hash in the import URL instead of a ref like "master" because later on I'll add HTTP caching to the imports and using specific hashes in the URL makes them immutable resources that are cached indefinitely.
I haven't updated the docs yet, but I'll be doing that shortly. There are also other shortcomings with this feature: the error messages for poorly formatted import statements is missing, caching is missing (I mentioned this one before) etc. I'll see if I get time to work on that. This repository is open-source after all, so I wouldn't mind some help.
@sudr-mg I will not be supporting Confluence imports. You should be able to add links to Confluence pages in your guidelines if you want. Nothing will stop that from working. But prguidelines will not be automatically importing from Confluence or anything that complicated.
@abhin Sounds good, I'll have a look at it. Thanks a lot! :)
@abhin this is awsome!
I tried using a snippet url was not working for me. Is this by design or am I doing something wrong
url of a repository file
<!-- import api/1.0/repositories/<team-name>/<guidelines-repo-name>/src/<hash-of-commit-from-guidelines-repo>/<filename.md> -->
url of a snippit file
<!-- import api/2.0/snippets/<team-name>/<some-code>/<hash-of-commit-from-guidelines-repo>/files/<filename.md>
If it is by design, would be nice to have this working.
@abhin I forgot to get back to you, it's working great for us! Although at the moment we are using master as the ref since we want to avoid having to update all repos when we update the guidelines. Give me a heads up when you enable caching if you can!
Perhaps it would be possible to add a webhook to the repo with the "master" guideline which would invalidate the cache when the file is updated?
@abhin-atl could this feature be codified in readme and maybe on the prguidlines homepage?
@rw_richard @sudr-mg I have good news. I just merged and deployed the ability to import guidelines. So now, you should be able to start your
CONTRIBUTING.mdfile with animportstatement that will be able to pull up guidelines from other files in other repositories. This will allow you to create a repository in your team that stores all the common guidelines. The syntax for this import is pretty primitive and I'll try to work on that later, but the current solution should help solve your problems. Let me illustrate how this will work with an example:For this to work, you will have to create markdown files in your "guidelines" repository that follow the usual prguidelines format. Then, for any repository that wants to import any of these files, you can start the CONTRIBUTING.md file in that repository with
The imported guideline could further import from elsewhere and prguidelines will follow the import chain. The imports will time out in 5 seconds.
I recommend using specific hash in the import URL instead of a ref like "master" because later on I'll add HTTP caching to the imports and using specific hashes in the URL makes them immutable resources that are cached indefinitely.
I haven't updated the docs yet, but I'll be doing that shortly. There are also other shortcomings with this feature: the error messages for poorly formatted import statements is missing, caching is missing (I mentioned this one before) etc. I'll see if I get time to work on that. This repository is open-source after all, so I wouldn't mind some help.
@sudr-mg I will not be supporting Confluence imports. You should be able to add links to Confluence pages in your guidelines if you want. Nothing will stop that from working. But prguidelines will not be automatically importing from Confluence or anything that complicated.