Provide better docs for contributors about running and debugging test projects

[edusperoni]

📚 Docs or angular.io bug report

Description

The developer documentation should have a few examples and proper documentation on how to setup a contributing environment.

🔬 Minimal Reproduction

What's the affected URL?**

https://github.com/angular/angular/blob/master/docs/DEVELOPER.md

Anything else relevant?

I've been wrestling for a few hours with the repo and I'm still not able to properly setup a development environment for contributing. Ideally I'd like to test the changes I'm doing on a demo application before writing the tests, for example.

The documentation states how to run unit tests and build the npm packages, but that isn't very performant for running together with yarn link, even when using ibazel and linking dist/bin/packages/<package>/npm_package.

When working at the 8.2.13, I had to do some additional changes so the cli of my demo project would not complain about version 0.0.0 or that 8.2.13.with-local-changes was an invalid version.

I imagine I'm doing something very wrong, but unfortunately the documentation isn't helpful in this situation.

Asking around in gitter and other channels also yielded no result.

[kapunahelewong]

@edusperoni this might not be exactly what you're looking for since my workflow is specifically for working on the docs, but does this help you? My workflow

[gkalpak]

This sounds like a duplicate of #31908.

[edusperoni]

@kapunahelewong Unfortunately not exactly. Let me try to rephrase it:

Say I want to change code in @angular/core. Ideally I'd open a test application, change packages/core/src/refs.ts and it would automatically refresh this application with my changes.

Rebuilding all npm packages is an option, like what is suggested on #31908, but that seems way too heavy (multiple bundle generation every change and having to call the whole build again instead of running in watch mode), considering ibazel build //packages/core runs in a small fraction of that time.

I guess if I'd rephrase it into a question, it'd be: If I want to make a change to an angular package, how should I setup my dev environment so I could "test" (not unit/e2e testing) those changes?

[s-gbz]

Hey, that sounds a lot with what I've been up to recently. I'm happy to say that it finally works for me. If you can build packages localy on your machine "@angular/common": "file:../../angular/dist/packages-dist/common", might (/will?) be the quickest way since you can have bazel in watch mode.

Unfortunately though this only works on limited packages for me. E.g. including core & common is fine, but forms and module fail on unresolved dependencies.

In case you happen to struggle with peer dependencies (they're crucial!), just add them like so:

  "dependencies": {
    "@angular/animations": "~7.2.0",
    "@angular/common": "~7.2.0",
    "@angular/compiler": "~7.2.0",
    "@angular/core": "~7.2.0",
    "@angular/forms": "~7.2.0",
    "@angular/platform-browser": "~7.2.0",
    "@angular/platform-browser-dynamic": "~7.2.0",
    "@angular/router": "https://123456-123456-gh.circle-artifacts.com/0/angular/router-pr12345-1a2b3c.tgz",
    "core-js": "^2.5.4",
    "rxjs": "~6.3.3",
    "tslib": "^1.9.0",
    "zone.js": "~0.8.26"
  },
  "peerDependencies": {
    "@angular/core": "7.2.15",
    "@angular/common": "7.2.15",
    "@angular/platform-browser": "7.2.15",
    "@angular/compiler": "https://123456-123456-gh.circle-artifacts.com/0/angular/compiler-pr12345-1a2b3c.tgz",
    "zone.js": "0.10.2",
    "rxjs": "~6.3.3"
  },

An alternative is using artifacts from circleci - and yeah that is slower than building a single package localy, but hey gotta take what's given, right?

---

PS: Feel free to hit me up if you're stuck in the process (I've been there and it sucked). I'm also going to write a little blog post to adress this subject soon - please add further insights to #31908

[edusperoni]

@s-gbz Thanks! I'll try your solution today.

I'm trying to understand how the angular team actually develops the framework. Do they just write the tests before the feature and test once it all passes?

[kapunahelewong]

Oh, @edusperoni, thanks for clarifying. I wish I knew the answer - I'm still learning. :)

[SchnWalter]

I would also like to see some more information about how to debugg tests, but also an improved PR submission checklist, because on each push for #36897, I've discovered something new that I need to check: a new command or a new requirement.

[kapunahelewong]

cc @aikidave (docs team lead) fyi

[aikithoughts]

This is good information! I'll talk with folks and see how we can provide better information for you!

[cerkiner]

What is the ETA on this? Is there any other online resource about running angular local fork? I am currently unable to test my changes, therefore unable to raise pull requests and contribute to angular.

[aikithoughts]

I'm afraid I don't have an ETA to share as yet. The documentation team is working through our backlog as best we can! Thanks for your patience.

[SchnWalter]

The "Running Tests Locally" section of docs/DEVELOPER.md doesn't seem to be enough to run all tests locally and the AIO pipelines fail if you make certain changes and you don't run those tests.

See #37389 (comment) and #37389 (comment)

[FrancescoBorzi]

Any news about this? It would be nice to have more information about how to contribute.

I can only find information about how to properly write commit names etc... but I can't figure out how I can set up a working environment where I can easily modify the Angular code and see it in action in a demo app.

[aikithoughts]

I'm afraid I don't have more news yet. I got caught up with version 10 and some other items. I'm going to bring this up in a meeting later and I'll try to get a plan together!

(If you want to contribute to the documentation, I can definitely help with that, though! :) )

[angular-robot]

Just a heads up that we kicked off a community voting process for your feature request. There are 20 days until the voting process ends.

Find more details about Angular's feature request process in our documentation.

[angular-robot]

Thank you for submitting your feature request! Looks like during the polling process it didn't collect a sufficient number of votes to move to the next stage.

We want to keep Angular rich and ergonomic and at the same time be mindful about its scope and learning journey. If you think your request could live outside Angular's scope, we'd encourage you to collaborate with the community on publishing it as an open source package.

You can find more details about the feature request process in our documentation.

[jessicajaniuk]

We have done some updating to DEVELOPER.md, but it's probably still a little out of date. There is now more information on running tests locally though. So in the meantime, hopefully things are a little better.

[JeanMeche]

The relevant part is:

angular/docs/DEVELOPER.md

Lines 95 to 119 in 5bd188a

	### Testing changes against a local library/project
	Often for developers the best way to ensure the changes they have made work as expected is to run
	use changes in another library or project. To do this developers can build Angular locally, and
	using `yarn link` build a local project with the created artifacts.
	This can be done by running:
	```sh
	yarn ng-dev misc build-and-link <path-to-local-project-root>
	```
	### Building and serving a project
	#### Cache
	When making changes to Angular packages and testing in a local library/project you need to run `ng cache disable` to disable the Angular CLI disk cache. If you are making changes that are not reflected in your locally served library/project, verify if you have [CLI Cache](https://angular.io/guide/workspace-config#cache-options) disabled.
	#### Invoking the Angular CLI
	The Angular CLI needs to be invoked using Node.js [`--preserve-symlinks`](https://nodejs.org/api/cli.html#--preserve-symlinks) flag. Otherwise the symbolic links will be resolved using their real path which causes node module resolution to fail.
	```sh
	node --preserve-symlinks --preserve-symlinks-main node_modules/@angular/cli/lib/init.js serve
	```

About running the docs with adev, this is now simplier we have yarn docs.

With this I think we can close this issue. If ever someone needs more help, feel free to open a new issue or reach out on community discord :)

[angular-automatic-lock-bot]

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}