refactor(docs): update the contributing docs #17585

ckipp01 · 2023-05-25T13:22:07Z

This makes a bunch of small updates the contributing docs that were
recently migrated over from the scala-lang site. I think there are
actually some more updates to be done, but much of these changes are
just structural. To sort of summarize this does the following:

gets rid of old irrelevant things like the checklist.sh
removes some instructions that are no longer relevant
re-organizes the side bar to better group things by topic
gets rid of redundant information and tries to group things better
moves the scaladoc docs into the contributing docs

I'll add some more comments inline to further explain.

[skip community_build]

Old sidebar

New sidebar

ckipp01 · 2023-05-25T13:23:49Z

docs/_docs/contributing/checklist.sh

I checked with @Kordyjan and this is no longer being used, so I just removed it since it's outdated.

ckipp01 · 2023-05-25T13:24:12Z

docs/_docs/contributing/debug-tests.md

The information that was in here is now included in the other-debuggin.md page.

ckipp01 · 2023-05-25T13:24:49Z

docs/_docs/contributing/getting-started.md

@@ -43,7 +50,6 @@ Start by cloning the repository:
 ```bash
 $ git clone https://github.com/lampepfl/dotty.git
 $ cd dotty
-$ sbt managedSources # Needed for IDE import to succeed


I've never used this and testing with Metals, this doesn't seem to be necessary.

Excellent! Reading the current version, I was just going to say we should remove this!

docs/_docs/contributing/index.md

ckipp01 · 2023-05-25T13:32:59Z

docs/_docs/contributing/issues/efficiency.md

Another one that I'll want your thoughts on @anatoliykmetyuk. This is a cool example, but also very Sublime specific. I'm not sure how helpful or relevant this really is to people contributing. What do you think?

ckipp01 · 2023-05-25T13:34:26Z

docs/_docs/contributing/scala2-vs-scala3.md

I really didn't think this added anything to the guide. It's useful but also captures in other various places.

ckipp01 · 2023-05-25T13:35:11Z

docs/_docs/contributing/tools/ide.md

There was multiple places where there was IDE related stuff to I put them all together in the setting-up-your-ide.md.

ckipp01 · 2023-05-25T13:35:24Z

docs/_docs/contributing/tools/mill.md

I wasn't really sure why this was here.

ckipp01 · 2023-05-25T13:35:34Z

docs/_docs/contributing/tools/scalafix.md

Same with this one, I didn't see why this was part of this guide.

ckipp01 · 2023-05-25T13:35:59Z

scaladoc/README.md

Instead of having some stuff in readmes and others in the guide I moved all this information to a scaladoc section of the contributing guide.

docs/_docs/contributing/scaladoc.md

julienrf

Overall, I think this is a great improvement, thank you! I am a bit worried about all the URL changes, though. I know we don’t promise stable URLs in this website but I am not very comfortable with breaking many of the previous URLs. Would you mind adding a redirectFrom directive in the frontmatter of the changed pages to keep the old URLs working?

ckipp01 · 2023-05-25T14:47:42Z

Overall, I think this is a great improvement, thank you! I am a bit worried about all the URL changes, though. I know we don’t promise stable URLs in this website but I am not very comfortable with breaking many of the previous URLs. Would you mind adding a redirectFrom directive in the frontmatter of the changed pages to keep the old URLs working?

Do we need to worry about that here though? Since this is actually never part of the stable reference it does give us a bit of flexibility here to really just ensure that the contributing link works, and from there, who knows. I can totally do it, just want to be sure it's worth it.

som-snytt · 2023-05-25T14:58:55Z

As someone who has bookmarked these unstable URLs in the past and was annoyed to update them, I think it is not worth the added effort on your part here and also forever in the future.

Also, thanks, I've already benefited from reading this PR!

Dedelweiss · 2023-05-25T15:25:53Z

I see a cheatsheet.md page but I don't see it in any part.

Dedelweiss · 2023-05-25T15:28:14Z

Strange, the list bugs for cause.md on my generated document but not on the preview.

ckipp01 · 2023-05-26T08:02:55Z

Strange, the list bugs for cause.md on my generated document but not on the preview.

This is super odd, I have no idea where the 4 comes from there. I'll try to minimize because maybe this is just a general bug that we're hitting on with scaladoc.

This makes a bunch of small updates the contributing docs that were recently migrated over from the scala-lang site. I think there are actually some more updates to be done, but much of these changes are just structural. To sort of summarize this does the following: - gets rid of old irrelevant things like the `checklist.sh` - removes some instructions that are no longer relevant - re-organizes the side bar to better group things by topic - gets rid of redundant information and tries to group things better - moves the scaladoc docs into the contributing docs I'll add some more comments inline to further explain. [skip community_build]

julienrf

Thank you!

mbovel · 2023-05-30T13:52:25Z

It's really great that this PR introduced a ”Setup your IDE” page as this is very central to getting started on Dotty.

I think the "build server" part for VS Code would deserve to be detailed/emphasized/pushed to the front even more. As an example, here are the instructions I sent to newcomers to the Spree today: #17211 (comment). These seem to be the most important steps to me.

ckipp01 · 2023-05-30T14:12:46Z

It's really great that this PR introduced a ”Setup your IDE” page as this is very central to getting started on Dotty.

I think the "build server" part for VS Code would deserve to be detailed/emphasized/pushed to the front even more. As an example, here are the instructions I sent to newcomers to the Spree today: #17211 (comment). These seem to be the most important steps to me.

Ah sure, I can expand that section.

This is a follow-up from the comment [here](scala#17585 (comment)) and just adds a bit more details about making sure you import the project correctly.

This is a follow-up from the comment [here](scala#17585 (comment)) and just adds a bit more details about making sure you import the project correctly. [skip community_build]

#17628) This is a follow-up from the comment [here](#17585 (comment)) and just adds a bit more details about making sure you import the project correctly. [skip community_build]

This makes a bunch of small updates the contributing docs that were recently migrated over from the scala-lang site. I think there are actually some more updates to be done, but much of these changes are just structural. To sort of summarize this does the following: - gets rid of old irrelevant things like the `checklist.sh` - removes some instructions that are no longer relevant - re-organizes the side bar to better group things by topic - gets rid of redundant information and tries to group things better - moves the scaladoc docs into the contributing docs I'll add some more comments inline to further explain. [skip community_build] _Old sidebar_ <img width="321" alt="Screenshot 2023-05-25 at 15 18 32" src="https://github.com/lampepfl/dotty/assets/13974112/2e493110-8098-445c-b101-166998c7c95f"> _New sidebar_ <img width="321" alt="Screenshot 2023-05-25 at 15 18 03" src="https://github.com/lampepfl/dotty/assets/13974112/2f86764e-bc3e-4356-9f56-006197a10153"> [Cherry-picked 28915c4]

#17628) This is a follow-up from the comment [here](#17585 (comment)) and just adds a bit more details about making sure you import the project correctly. [skip community_build] [Cherry-picked b2aaec8]

Backports #17585 to the LTS branch. PR submitted by the release tooling.

ckipp01 force-pushed the contributingDocs branch from da8ec20 to 6347232 Compare May 25, 2023 13:26

ckipp01 commented May 25, 2023

View reviewed changes

ckipp01 force-pushed the contributingDocs branch from 6347232 to 7fe47ff Compare May 25, 2023 13:41

julienrf reviewed May 25, 2023

View reviewed changes

docs/_docs/contributing/scaladoc.md Show resolved Hide resolved

julienrf reviewed May 25, 2023

View reviewed changes

ckipp01 added 3 commits May 29, 2023 11:54

refactor: make sure cheatsheet is in the sidebar

5076321

docs: add in redirects for contributing pages

c8b55ba

ckipp01 force-pushed the contributingDocs branch from 6de6d6a to c8b55ba Compare May 29, 2023 10:01

ckipp01 requested a review from julienrf May 29, 2023 10:02

julienrf approved these changes May 30, 2023

View reviewed changes

ckipp01 merged commit 28915c4 into scala:main May 30, 2023

ckipp01 deleted the contributingDocs branch May 30, 2023 10:59

ckipp01 mentioned this pull request May 30, 2023

docs(contributing): show an example of how to switch your build server #17628

Merged

Kordyjan mentioned this pull request Nov 17, 2023

Backport "refactor(docs): update the contributing docs" to LTS #18960

Merged

Kordyjan added a commit that referenced this pull request Nov 20, 2023

Backport "refactor(docs): update the contributing docs" to LTS (#18960)

e0ab663

Backports #17585 to the LTS branch. PR submitted by the release tooling.

Kordyjan added this to the 3.3.2 milestone Dec 14, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(docs): update the contributing docs #17585

refactor(docs): update the contributing docs #17585

ckipp01 commented May 25, 2023 •

edited

Loading

ckipp01 May 25, 2023

ckipp01 May 25, 2023

ckipp01 May 25, 2023

mbovel May 30, 2023

ckipp01 May 25, 2023

ckipp01 May 25, 2023

ckipp01 May 25, 2023

ckipp01 May 25, 2023

ckipp01 May 25, 2023

ckipp01 May 25, 2023

julienrf left a comment

ckipp01 commented May 25, 2023

som-snytt commented May 25, 2023

Dedelweiss commented May 25, 2023

Dedelweiss commented May 25, 2023

ckipp01 commented May 26, 2023

julienrf left a comment

mbovel commented May 30, 2023

ckipp01 commented May 30, 2023

refactor(docs): update the contributing docs #17585

refactor(docs): update the contributing docs #17585

Conversation

ckipp01 commented May 25, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

julienrf left a comment

Choose a reason for hiding this comment

ckipp01 commented May 25, 2023

som-snytt commented May 25, 2023

Dedelweiss commented May 25, 2023

Dedelweiss commented May 25, 2023

ckipp01 commented May 26, 2023

julienrf left a comment

Choose a reason for hiding this comment

mbovel commented May 30, 2023

ckipp01 commented May 30, 2023

ckipp01 commented May 25, 2023 •

edited

Loading