search

ladybug-tools / community

Ladybug Tools community content
MIT License
2 stars 0 forks source link

Branch- and release-driven development #2

Open theo-armour opened 5 years ago

theo-armour commented 5 years ago

@antoinedao

I would really like to move the Spider coding workflow over to a release- and branch-driven very git-oriented workflow. I do, however, have several stumbling blocks I have not figured out how to work-around yet.

Looking for:

In other words the entire history of a project - from R1 to the latest release - is always viewable and runnable by non-technical users and every release is in its own branch.

Using a CDN such as jsDelivr it is easy to link to any asset in any branch or release on GitHub.

What is not so easy is to get a link to the the multiple primary HTML files that can run and load all the relevant scripts and other assets.

Feel free to request more explanation. Any suggestions appreciated.

AntoineDao commented 5 years ago

I think the easiest strategy to achieve your goals here is to deploy to versioned folders on gh-pages. You could then deploy each release in a specific folder on gh-pages as well as overwriting the latest folder. Here is a partial example on spider-core (which only has latest because no new version has been published since setting this system up).

This would result in users being able to hit the following URLs:

I know I have been pestering with this but I would strongly recommend following semantic versioning rather than using manual revision names as it will remove the overhead of manual releases anytime you make small or large changes. It will also indicate to your users the scope of change you have made as well as facilitate releasing html artifacts in your github releases (here is an example of the ladybug package releases on github).

theo-armour commented 5 years ago

@AntoineDao

Re deployment strategies

You could then deploy each release in a specific folder on gh-pages as well as overwriting the latest folder.

Nice one. I have been doing the former but not the latter. Instead I have use an index.html to redirect you to the folder with the latest rev. And this has been confusing peeps - because you end up with a link to whatever that release is and this eventually goes out of date.

For example, currently the canonical link: http://www.ladybug.tools/spider-gbxml-fixer/[index.html] takes you to: http://www.ladybug.tools/spider-gbxml-tools/spider-gbxml-fixer/rXX/spider-gbxml-fixer.html

With your idea, this could be replaced by, for example:

http://www.ladybug.tools/spider-gbxml-fixer/dev//[index.html] << frequent updates and: http://www.ladybug.tools/spider-gbxml-fixer/build//[index.html] << occasional updates

with archived releases copied from /build to: http://www.ladybug.tools/spider-gbxml-fixer/rXX//[index.html]

I had something like this going with earlier releases of the viewer, but then stuff happened and we ended up having two dev releases. ;-)

Anyway, I will try this with the Fixer.

Of course this means ending up with live folders for each rev in all releases which is wasteful I know. But it's what my guts is tell me to do.

Semantic versioning is another thing. I will open up a separate issue for that in the next day or so.

Thank you for your advice.

AntoineDao commented 5 years ago

I reckon the /Dev, /build, /release-x set up is a bit of an anti pattern that might confuse users. Surely users care for working versions of your code rather than draft/Dev versions? I'd reccomend sticking to /latest and /release-x. Any drafts or WIP can/should live in a separate branch or PR. Similarly iterative versions of your code shouldn't really be in different folders but just be overwritten (don't worry, git will keep a history of it for you ;) )

theo-armour commented 5 years ago

@AntoineDao

the /Dev, /build, /release-x set up is a bit of an anti pattern that might confuse users.

For sure, confuses me too. There are several issues here.

The first is that the dev release is the one that needs testings by users - none of whom are developers. They just want a link that they can click and it runs. Furthermore, they may have been in contact with the developer regarding a file they want to validate that fails in the build version and want to see if it the issue response is updated in the dev version

Ditto the developer. I need to be able to check how the actual site behaves online as well.

Similarly iterative versions of your code shouldn't really be in different folders but just be overwritten (don't worry, git will keep a history of it for you ;) )

For sure, but then you need to run a git command the run the script. As I stipulated in the OP, there has to be a way of viewing earlier releases in action with a single click ( by a naive user). This is because earlier versions - especially with Spider gbXML Viewer - have features that were not yet carried forward to later releases.

In other words (in my utopia anyway), all versions are always runnable with a single click.

AntoineDao commented 5 years ago

Some more thoughts:

1. /dev, /build, /release-x

I think sticking to /latest and /release-x (or semantic-versioning /x.y.z) will solve the issue of just having a link to click to get to every version. Your /latest being the version you're currently working on.

2. folder structure

Your release branch (gh-pages) and you master development branch are not the same. What I mean by this is that you master dev branch should NOT store things in versioned folders but just overwrite itself and version based on actual code differences to the project. The release branch however can be structured in the following way:

This means that developpers can review and follow the changes you have made to code and testers/users can access any given version/release of your code easily.

Does this make sense? I realise disccusing branches, releases, versioning and all of this without images or examples is not the easiest to convey clearly so apologies for that.

AntoineDao commented 5 years ago

Furthermore, I would be keen to move this issue to a Spider repo as it seems to be very spider specific. All the other bugs have their versioning, releasing and documentation setup pretty much sorted and do not have the same requirements. What do you think @theo-armour ?

theo-armour commented 5 years ago

@AntoineDao

  1. /dev, /build, /release-x

This pattern has been used by Mr.doob/Three.js for about ten years so it's one I am familiar with. Also, for quite a while Michal was doing some hard testing - and giving his thumbs up when he felt things were good - so the build version had some proven stability but unfortunately he has not had the time to do that since R12.

  1. folder structure

Can you create a demo or test repo with the way you see folders and branches set up? Then I can try to to populate the folders with stuff and establish a workflow that suitably productive?

Furthermore, I would be keen to move this issue to a Spider repo as it seems to be very spider specific.

Interesting. I didn't see things being Spider-specific but much about newb, plain-vanilla and full-stack can interact successfully. But sure, this can go anywhere. It's just nice to be able to discuss these things.

AntoineDao commented 5 years ago

/dev, /build, /release-x

Ah! I think we're not talking about the same thing 😆 I am referring to folders on the gh-pages branch. Holding a dev/ and master branch works. I know release specific branches are used also but I think this is mostly for Long Term Support requirements and such so i reckon we can just rely on git tags/releases to keep track of releases.

theo-armour commented 5 years ago

@AntoineDao

You are correct Ricardo (Mr.doob) uses master (build) and dev branches with LTS files available in releases. This is is fine and works just fine for most people/most situations.

Unfortunately, I am a nutcase and don't just want just to load the older JS files, I also want to be able to open and run the older HTML files.

So, for example. I wrote this script:

http://jaanga.github.io/documents/threejs-viewers/threejs-viewer-timeline/threejs-viewer-timeline-r1-@.html

This script allows you to run any of the examples in a Three.js release using the release the example was built for. It loads HTML into the srcdoc of an iframe, hacks links and does naughty things. I've not updated it in a while so there's more luck with examples from earlier releases.

The mission as always is to show newbs that the progression from R1 to RXXX is not magic but is based on persistent, engaged human effort.

Anyway. what I think I should do is write down the way I should be contributing to my own efforts and then let you make comments that help me take some steps (there can be many but they should be small) toward better ways of doing thing