Contributing to the Wiki

[mottosso]

Hi all,

I've added a page to the Wiki on releasing packages, and have a few ideas on how to improve the experience.

• https://github.com/nerdvegas/rez/wiki/Releasing-Packages

The Problem

1. Edits to the wiki go unnoticed, no notifications. :(
2. Edits cannot be part of a PR with related code, and thus not commented on or iterated on collaboratively
3. The Wiki is versioned, but separately from the parent repo git commits
4. The Wiki and current version of Rez are disconnected; meaning that if you run an older version of Rez, you've got no documentation. The Wiki is only able to display its contents at a single point in time.

A solution(s)

1. Store the Wiki in the parent repo, and automagically deploy it on push; e.g. rez\wiki. That solves (1), (2) and (3), in that we can now make PRs with both code and documentation changes. Win! But it doesn't solve (4), which is a bummer..
2. Host the documentation in the parent rez repo, but publish it elsewhere, like readthedocs. Then each version could get tagged along with a particular version of the Rez source, and updates could be made retroactively to an older version, whilst still displaying multiple versions of the docs to the end-user. Win!

An example of docs with multiple versions.

• https://docs.python.org/2/index.html

See top of page.

[bpabel]

+1 for readthedocs. Especially if docs can be migrated to something like sphinx that can take advantage of autodoc features.

[uncojohnco]

+1 readthedocs

[nerdvegas]

Hey Marcus, Please don't update the wiki directly - I didn't realise that you could! There is a process for contributing to the wiki already, see https://github.com/nerdvegas/rez/blob/master/wiki/README.md. I agree that lack of versioned docs is a problem, and I'm open to migrating to something like readthedocs. It's just one of those things I haven't had the time to do. Fortunately, half the work (wiki stored in parent repo) is already done - it would just be a matter of updating the update-wiki.sh script to export the content to a different platform (eg readthedocs). With regards to the content itself. Thanks for the input, and I'll make sure that the info you have there is conveyed in the docs when I update them (until I do this, I have left your content there and unchanged. It won't be overwritten by the update-wiki script just yet, because there happens to not be an entry for that page). There are a few aspects that I don't think quite convey the role of rez-release correctly though. For example, you state that rez-release makes the assumption that "You make releases from your local machine (e.g. you do not release via continuous integration)". I don't think this is necessarily true. For example, you could have CI in place that runs as a PR merge hook - when a PR is merged, the CI script checks out master, runs the unit tests, and actually runs rez-release itself, thus installing the package and tagging the repo appropriately. "You use Git tags as version numbers" is also not quite correct - you can change the tag name via the plugins.release_vcs.tag_name config setting. In any case, I think that the docs on package releasing should explain what rez-release does, but also emphasize that you don't have to use it - as you mention, it could be just as valid to release via CI triggered on a tag, using "rez-build --prefix" (indeed, that's part of the reason that --prefix is there in the first place). I've updated the permissions to block direct wiki editing now. Bear in mind that even if I allowed it, the update-wiki.sh script would overwrite the content on next execution anyway. Thx A

…

On Fri, Apr 19, 2019 at 3:20 AM Marcus Ottosson ***@***.***> wrote: Hi all, I've added a page to the Wiki on releasing packages, and have a few ideas on how to improve the experience. - https://github.com/nerdvegas/rez/wiki/Releasing-Packages *The Problem* 1. Edits to the wiki go unnoticed, no notifications. :( 2. Edits cannot be part of a PR with related code, and thus not commented on or iterated on collaboratively 3. The Wiki is versioned, but separately from the parent repo git commits 4. The Wiki and current version of Rez are disconnected; meaning that if you run an older version of Rez, you've got no documentation. The Wiki is only able to display its contents at a single point in time. *A solution(s)* 1. Store the Wiki in the parent repo, and automagically deploy it on push; e.g. rez\wiki. That solves (1), (2) and (3), in that we can now make PRs with both code and documentation changes. Win! But it doesn't solve (4), which is a bummer.. 2. Host the documentation in the parent rez repo, but publish it elsewhere, like readthedocs. Then each version could get tagged along with a particular version of the Rez source, and updates could be made retroactively to an older version, whilst still displaying multiple versions of the docs to the end-user. Win! An example of docs with multiple versions. - https://docs.python.org/2/index.html See top of page. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#600>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAMOUSSDIVYJTPOZDT6KCDLPRCUV7ANCNFSM4HG64GKQ> .

[mottosso]

Please don't update the wiki directly ... There are a few aspects that I
don't think quite convey the role of rez-release correctly though ... not quite correct

No worries, was expecting my blunt initiative and strong assertions to prompt clear direction and corrections so this is great. :)

That wiki/ folder is great and already accounts for problems 1-3, and I'm not too fussed about multiple version support at the moment myself.

[nerdvegas]

Closing for now, readthedocs would be nice but will open separate enhancement issue for this at a later date

[mottosso]

I had a look at contributing via the wiki/ directory, but it doesn't seem up to date with the current version.

• https://github.com/nerdvegas/rez/wiki/Configuring-Rez#package_filter
• https://github.com/nerdvegas/rez/blob/master/wiki/pages/_Configuring-Rez.md

I suspect this hasn't been pushed to the Wiki for some time. I would update it, but since edits have been disabled, fetching the original markdown is unavailable too.

For my future self, what I'm looking to update is the section about package_filter, which currently only contains a YAML reference (despite surrounding topics being Python) (and which I'm not sure how use)

1. How to use it with rezconfig.py
2. How to use it with an environment variable.

rezconfig.py

package_filter = {'excludes': 'glob(*-beta*)'}

environment

set REZ_PACKAGE_FILTER_JSON="{'excludes': 'glob(*-beta*)'}"

[nerdvegas]

The "Configuring Rez" page is a special case - its content is derived directly from rezconfig.py.

Note this comment in rezconfig.py:

Note: The comments in this file are extracted and turned into Wiki content. Pay
attention to the comment formatting and follow the existing style closely.