Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adjust Visual Studio compilation guide to account for new contributors #1927

Merged
merged 4 commits into from
Oct 5, 2022

Conversation

olanti-p
Copy link
Contributor

@olanti-p olanti-p commented Sep 30, 2022

Summary

SUMMARY: Other "Adjust Visual Studio compilation guide to account for new contributors"

Purpose of change

Attempt to prevent new contributors from making the same mistakes by adjusting and expanding the documentation.

List of issues:

  1. Microsoft by default collects some telemetry which may (or may not) be undesirable
  2. People often open PRs not knowing there is a code style they're supposed to adhere to
  3. Installing the Astyle extension from source is somewhat confusing for people who attempt such a thing for the first time
  4. People attempt to grab the Astyle extension for VS2019 from Visual Studio Marketplace but can't find it there
  5. It's not quite clear that astyle means Artistic Style
  6. The astyle installation doc is backwards: it goes from the complex solution of pre-commit hook to the simple make astyle
  7. The images used by extension installation instructions are hosted on GitHub and can't be viewed offline
  8. People often skip the "Configure Working Directory" step when trying to run directly from Visual Studio
  9. It may not be clear how to configure the working directory for people that use VS for the first time
  10. People often run the game on Debug configuration and wonder where did their performance go (Debug builds in VS may be an order of magnitude slower than Release ones)

Describe the solution

  1. Port over set "disable MS telemetry" flag in VCPKG setup script CleverRaven/Cataclysm-DDA#41460
  2. Add a section on code style that links to the main astyle doc, add a note in requirements that refers to the section, add a warning for automatic code style checks.
  3. Add instructions on how to compile the extension for VS2019 from source.
  4. Add a disclaimer that the Marketplace won't help here
  5. Add a note that astyle is short for Artistic Style
  6. Make a clear separation between invocation options, go from basic ones to more complex or platform-specific
  7. Download the images, put them in doc/img/ and use local links
  8. Add working directory configuration as a separate compilation step that refers to the corresponding section
  9. Make the instructions more detailed
  10. Discourage the use of Debug configuration by insinuating it's for power users :)
    Add explanation on Debug vs Release builds, and suggest the latter for one-off compilations.

Testing

Guess we'll just have to monitor #development channel for a few months

olanti-p and others added 3 commits October 1, 2022 02:07
MS collects telemetry on users who don't explicitly opt-out of vcpkg telemetry by passing the "-disableMetrics" option to the bootstrap batch file. Since users are going to be essentially piping curl into bash with this setup guide without thinking about what's going on, let's set the defaults to something more end-user friendly.

(cherry picked from commit 5c9a51b02d11d547ad88128b6499e3d06df45b3c)
@olanti-p olanti-p marked this pull request as draft October 3, 2022 18:51
@olanti-p olanti-p marked this pull request as ready for review October 3, 2022 19:11
@Coolthulhu Coolthulhu self-assigned this Oct 5, 2022
@Coolthulhu Coolthulhu merged commit 688d485 into cataclysmbnteam:upload Oct 5, 2022
@olanti-p olanti-p deleted the adjust-vs-guide branch October 18, 2022 21:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants