Merge pull request #8851 from NuGet/main

[ReleasePrep][2021.10.15]FI of main into dev

Author: loic-sharma

README.md

@@ -1,53 +1,30 @@
-[NuGet Gallery](http://nuget.org/) — Where packages are found 
+[NuGet Gallery](https://www.nuget.org/) — Where packages are found 
 =======================================================================
 
-This is an implementation of the NuGet Gallery and API. This serves as the back-end and community 
-website for the NuGet client. For information about the NuGet project, visit the [Home repository](https://github.com/nuget/home).
+This  project powers [nuget.org](https://www.nuget.org), the home for .NET's open-source ecosystem. For information about NuGet, visit the [Home repository](https://github.com/nuget/home).
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
 
-## Build and Run the Gallery in (arbitrary number) easy steps
+## Getting started
 
-1. Prerequisites:
-    1. Visual Studio 2019 - Install the following `Workloads`:
-        * ASP.NET and web development
-        * Azure development
-    2. PowerShell 4.0
-    3. SQL Server 2016
-        * For development purposes connection strings point to `(localdb)\mssqllocaldb`, make sure that the DB engine version 13.0 or greater is being used (check by running `sqllocaldb info mssqllocaldb` in the command line).
-2. Clone it!
-    
-    ```PS C:\Code> git clone https://github.com/NuGet/NuGetGallery.git```
-3. Build it!
-    
-    ```
-    PS C:\Code> cd NuGetGallery
-    PS C:\Code\NuGetGallery> .\build
-    ```
-4. Set up the website!
+First install prerequisites:
 
-    ```PS C:\Code\NuGetGallery> .\tools\Setup-DevEnvironment.ps1```
-    
-5. If you would like to configure your gallery instance to use MSA/AAD, please follow the steps listed [here](https://github.com/NuGet/NuGetGallery/wiki/Configuring-MSA-AAD-for-your-on-prem-gallery-instance).
+1. Visual Studio 2019 - Install the following [`Workloads`](https://docs.microsoft.com/visualstudio/install/modify-visual-studio):
+    * ASP.NET and web development
+    * Azure development
+2. PowerShell 4.0
+3. SQL Server 2016 (with DB engine version 13.0 or greater)
 
-6. Ensure the `NugetGallery` project is the StartUp Project and press `F5` to run the site! That's it!
+Now run the NuGet Gallery:
 
-When working with the gallery, e-mail messages are saved to the file system (under `~/App_Data`).
-You can use an SMTP server instead by editing `src\NuGetGallery\Web.Config` and adding a `Gallery.SmtpUri`
-setting. Its value should be an SMTP connection string, such as: `smtp://user:password@smtpservername:25`.
-You can also turn off e-email confirmations by changing the value of `Gallery.ConfirmEmailAddresses` to `false`
-in the `src\NugetGallery\Web.Config` file.
+1. Clone the repository with `git clone https://github.com/NuGet/NuGetGallery.git`
+2. Navigate to `.\NuGetGallery`
+3. Build with `.\build.ps1`
+4. Create the database and enable HTTPS with `.\tools\Setup-DevEnvironment.ps1`
+5. Open `.\NuGetGallery.sln` using Visual Studio
+6. Ensure the `NuGetGallery` project is the StartUp Project and [press `F5` to run the site](https://docs.microsoft.com/visualstudio/get-started/csharp/run-program)
 
-Visual Studio may modify the `applicationhost.config` file. You can force git to ignore changes to this file
-with:
-
-    git update-index --assume-unchanged .vs/config/applicationhost.config
-
-You can undo this with this command:
-
-    git update-index --no-assume-unchanged .vs/config/applicationhost.config
-
-This should help prevent unwanted file commits.
+Refer to [our documentation](./docs/) for information on how to develop the frontend, use AAD, and more.
 
 ## Deploy
 
@@ -94,6 +71,17 @@ This is the Git workflow we're currently using:
 
 Clone and checkout the `dev` branch.
 
+Visual Studio may modify the `applicationhost.config` file. You can force git to ignore changes to this file
+with:
+
+    git update-index --assume-unchanged .vs/config/applicationhost.config
+
+You can undo this with this command:
+
+    git update-index --no-assume-unchanged .vs/config/applicationhost.config
+
+This should help prevent unwanted file commits.
+
 ### When starting a new feature/unit of work.
 
 1.  __Pull the latest.__
@@ -146,3 +134,4 @@ Clone and checkout the `dev` branch.
 
 6.  __Be ready to guide your change through QA, Staging and Prod__
     Your change will make its way through the QA, Staging and finally Prod branches as it's deployed to the various environments. Be prepared to fix additional bugs!
+

docs/Emails.md

@@ -0,0 +1,9 @@
+# Emails
+
+By default, the Gallery saves e-mail messages to the file system under `src\NuGetGallery\App_Data`.
+
+You can use an SMTP server instead by editing `src\NuGetGallery\Web.config` and adding a `Gallery.SmtpUri`
+setting. Its value should be an SMTP connection string, such as `smtp://user:password@smtpservername:25`.
+
+You can require new accounts confirm their e-mail adddress by changing the value of `Gallery.ConfirmEmailAddresses`
+to `true` in the `src\NuGetGallery\Web.config` file.

docs/Frontend.md

@@ -0,0 +1,42 @@
+# Updating NuGet Gallery's frontend
+
+## Styling
+
+We use [Bootstrap 3](https://getbootstrap.com/docs/3.3/) as our base CSS framework.
+This provides a grid layout, CSS normalization, and some common styles.
+
+Changes to our styles should be made to [LESS](https://lesscss.org/) files and not to a CSS file directly.
+LESS is a syntax that itself is not usable by a browser but is compiled to CSS. It provides niceties that CSS
+does not offer such as rule nesting, mixins, variables, and arithmetic (calculated values).
+
+Each page may have its own set of specific styles. These page-specific styles are in a `page-*.less` file
+in the `src\Bootstrap\less\theme\` directory.
+
+### Prerequisites
+
+To compile LESS files:
+
+1. Install node: https://nodejs.org/en/download/
+1. Install Grunt: `npm install -g grunt`
+1. Navigate to `.\src\Bootstrap`
+1. Install NPM dependencies: `npm install`
+
+### Updating styling
+
+1. Update one or more `.less` files in the `src\Bootstrap\less` directory
+1. Navigate to `.\src\Bootstrap`
+1. Run `grunt`
+
+### Adding a new page
+
+1. Create a new `page-X.less` file in the `src\Bootstrap\less\theme\` directory
+1. Add the new page in `src\Bootstrap\less\theme\all.less`
+
+## JavaScript
+
+We use [jQuery](https://jquery.com/) and [Knockout.js](https://knockoutjs.com/).
+
+Common JavaScript should be added to `src\NuGetGallery\Scripts\gallery\common.js`.
+
+Each page may have its own custom logic. These page-specific scripts are in a `page-*.js` file
+in the `src\NuGetGallery\Scripts\gallery\` directory.

docs/README.md

@@ -2,5 +2,7 @@
 
 You can find documentation for:
 
+1. [Updating NuGet Gallery's frontend](Frontend.md)
 1. [Building, deploying, and managing a NuGet Gallery instance](Deploying/README.md)
-1. [Using Azure Active Directory authentication](Using-AAD.md)
+1. [Email configuration](Emails.md)
+1. [Using Azure Active Directory authentication](Using-AAD.md)