Docs: add more informaton to Architecture page #7984
Conversation
|
Thank you for your pull request and welcome to our community. We require contributors to sign our Contributor License Agreement, and we don't seem to have you on file. In order for us to review and merge your code, please sign up at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need the corporate CLA signed. If you have received this in error or have any questions, please contact us at cla@fb.com. Thanks! |
|
I did accept the CLA a few minutes before opening this PR so maybe it's taking a bit to update... |
|
Unsure if I should add the docs to the /versioned_docs/version-24.1/ |
|
Ops. I see some linting errors on my .md changes. |
|
Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Facebook open source project. Thanks! |
|
Thank you! The text added looks correct to me, great job!
It would be nice if the architecture page was not versioned - it's not API, so it'd not necessarily tied to any version. That said - for now please also update the versioned docs 🙂 |
SimenB
requested review from
rickhanlonii,
thymikee,
aaronabramov,
cpojer,
rubennorte and
mjesun
|
@Luanf if you can fix the conflict we can merge |
|
Hey @Luanf I just re-read the page and doesn't this seem a bit empty or out of place:
Is there a better place to put this content? Maybe in a code comment? |
|
Thanks for the review @rickhanlonii ! |
|
Could we instead put it into the code as comments where this is most relevant? |
|
As an user, I would like to be able to read somewhere on the online docs and find out more information about ordering & parallelization, and I think that was the reason #6957 got created (although it was only about parallelization, I thought ordering could go well with that info). As for adding code comments, I went quickly through the code and the ordering part seems reasonably well documented in TestSequencer.js. And although the parallelization part seems to be more scattered out, the info about the runInBand behavior is commented on testSchedulerHelper.js. But still I personally would think this info belongs to somewhere in the official docs. |
|
Check out this long comment: https://github.com/facebook/jest/blob/master/packages/jest-haste-map/src/index.ts#L147 I think we can do something similar here, and link to it from some other places. |
Luanf
force-pushed
the
update-architecture-docs
branch
from
cb6f551
to
eefa540
Compare
Luanf
force-pushed
the
update-architecture-docs
branch
from
eefa540
to
4d065d4
Compare
|
I had more time to take a look at this one so I went through the code and attempted to set out some updates to code comments for the Test Sequencer and the Test Scheduler. I've also removed the notes I had added to the website docs, although that was the point asked on #6957. Thanks for all your reviews so far and please let me know if there is something more I could do here 😄 |
There was a problem hiding this comment.
The comments look accurate to me 👍 If we can get more of Jest's key components documented in this fashion, then we can maybe update the architecture page with a rough overview (essentially the video in text form) and link to the files with the comments for more details. The comments are probably also more likely to stay up to date when making significant changes to a component.
|
Thank you! |
|
I had to dig through a lot of Google results to get to this issue. Keeping that in mind, I really don't think the decision to pull the documentation from the site and keep it in the code was the right one. This way I get greeted by an empty "Architecture" page, that just has a link to a 50 minute YouTube video instead of some structured text that I can fly over and find what I need. The text that @Luanf provided here (#7984 (comment)) was perfect, it was exactly what I was looking for and what a colleague was looking for just two weeks ago. I'd really recommend not having documentation in code only, where nobody will find it that reads the official documentation website. |
|
@akuji1993 Please feel free to send pull requests to add an architecture overview to the Jest docs. |
|
This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs. |
Summary
Update Architecture docs page with more information regarding how the order of test execution is decided and how Jest handles parallelization, as pointed in #6957.
Note: the issue was more directed to just the parallelization part, but I thought it made sense to add the test ordering information as well.
Please let me know if it would be better to move that information elsewhere or not including it at all.
It's my first contribution here so I'm very open to guidance. 😄