search

marko-js / marko

A declarative, HTML-based language that makes building web apps fun
https://markojs.com/
MIT License
13.35k stars 643 forks source link

It would be nice if CONTRIBUTING.md contained a link to test setup. #1003

Closed budden closed 6 years ago

budden commented 6 years ago

New Feature

Description

CONTRIBUTING.md asks that I (a potential contributor) run tests before I make my pull request. I installed marko as a dependency of marko-express (it was installed by npm install), so it does not have necessary packages to run tests. I installed several by hand but then get tired :) Maybe it should be obvious, but I'm not an experiences node.js user, so it is not evident for me.

Why

I and other users could fix easy issues more easily.

Is this something you're interested in working on?

Maybe.

jasonmacdonald commented 6 years ago

Are you trying to contribute something to the core Marko project, or something around the Express starter example? If the former, you should check out the main Markojs project from Github, not through NPM as that is the distribution version, not the core project. If the change is in the marko-express start project, again, check out the GitHub project for that, not NPM. NPM is typically a packaged version of a project, exported specifically for consumption as an NPM package, not as a GIT repository.

Hope that helps :)

mlrawlings commented 6 years ago

As @jasonmacdonald mentioned, if you clone the marko-js/marko repo, you'll have the tests set up. If you're wanting to develop on marko and see how it affects another project, you can use npm link. Here's how you would set things up with it:

1. Clone and install marko

cd ~
git clone git@github.com:marko-js/marko.git
cd marko && npm i

2. Clone and install marko-express

cd ~
git clone git@github.com:marko-js/marko.git
cd marko-express && npm i

3. Link marko (this creates a global link to marko, it's like you had npm i -g marko, but it's running from your cloned directory)

cd ~/marko
npm link

4. Link marko into marko-express (this creates a symlink in ~/marko-express/node_modules to your cloned directory)

cd ~/marko-express
npm link marko

5. You can now make changes in ~/marko and they will affect your copy of marko-express.

This can be a good way to track down and fix an issue that you're only seeing in a specific project. However, we'd also want to distill the source of the issue and create a minimal test case to commit to the Marko repo to prevent reintroducing the issue.

I'm not sure whether or not this info is something that should be in CONTRIBUTING or not. It's not a super common workflow. Even when debugging applications to look for a potential issue in Marko, I'll just use the debugger to step through the currently installed version, and if there's an issue I'll create a corresponding test in the main repo and then work there. There are cases where I link though.

I've been leaning towards keeping things short by only including information that is unique to Marko, so it's not intimidating or annoying to read. But maybe linking out to something like this article (one of the first google results for npm link) would be worth while. Or maybe even linking to this issue. Assuming I've answered your question.