Introduce pinning CadQuery to a specific commit in the docs

marcus7070 commented 4 years ago

When I use CadQuery for a specific project I always start by creating an environment where CadQuery and CQ-editor are pinned to specific commits (and sometimes a commit is from my fork instead of the official). There are a few reasons why I do this, and I believe it's a good practise that the docs should be encouraging (perhaps at the bottom of the installation page, under a heading like "pinned install").

The main reason is so that my project always works, even if I come back to it after years and several new releases of CadQuery/CQ-editor.
Sometimes I want a feature that isn't implemented in CadQuery yet. I can implement it, switch my project over to this new commit, and get on with work while the PR is reviewed.
Back when rotation was broken, I switched a project to a fork that had the features I needed and a quick and ugly patch applied to fix rotations. I'm sure if I went looking for it, that project would still work fine, even though that fork was never merged into CadQuery.
It's much easier to work from master this way. The more people we have on master, the more PRs and improvements we get.
It helps with a sense of ownership over the code. I'm in control of exactly what code I run. The main reason I switched from commercial CAD packages to open source is because I've lost a lot of work when my licensing situation changed, but now no-one can take CadQuery away from me. Even if Conda and GitHub disapear, my projects refer to commits and they could just as easily come from GitLab or even a local repo.

The main reason I want this in the docs, aside from making other user's projects better, is because it might help out when we are considering changes that would break backwards compatibility. I'm not saying it would remove the need for backwards compatibility, but having a solution like this in the docs might reduce the need for long term deprecation warnings and help us trim the codebase down a bit. Examples:

Unfortunately I use NixOS and I'm not sure how to pin CadQuery using the standard Conda installation. I suspect this will work, but I'm not aware if there are any CadQuery/CQ-editor specific details. If I get some spare time I'll make a VM, figure it out, write the method into the docs and make a PR myself (but I don't have much spare time at the moment).

adam-urbanczyk commented 4 years ago

This can be done with pip: https://pip.pypa.io/en/latest/reference/pip_install/#git . Is this what you are after (NB: pip can be mixed with conda)?

marcus7070 commented 4 years ago

Yeah, that's the idea. Suggest an environment.yml file for each project/model they produce, with something like:

dependencies:
  - pip:
    - git+https://github.com/cadquery/cadquery.git@9c69cb3b797469055730845b60136ce6813f02fc#egg=cadquery
    - git+https://github.com/cadquery/CQ-editor.git@23fc503d962518564a62b5cf7a0ea5edb62ce87d#egg=cq_editor

CadQuery / cadquery

Introduce pinning CadQuery to a specific commit in the docs #358