feat: old docs issues (#3195)

Co-authored-by: kevaundray <kevtheappdev@gmail.com>
Co-authored-by: josh crites <jc@joshcrites.com>
Co-authored-by: Tom French <15848336+TomAFrench@users.noreply.github.com>
Co-authored-by: Koby Hall <102518238+kobyhallx@users.noreply.github.com>
Co-authored-by: Tom French <tom@tomfren.ch>
Co-authored-by: github-merge-queue[bot] <github-merge-queue[bot]@users.noreply.github.com>
Co-authored-by: kek kek kek <andriy.n@obox.systems>
Co-authored-by: jfecher <jfecher11@gmail.com>

.github/workflows/build-docs.yml

@@ -8,17 +8,57 @@ on:
       - opened
       - synchronize
       - labeled
-  push:
-    paths:
-      - 'docs/**'
 
 jobs:
-
-  build_and_deploy:
+  add_label:
+    runs-on: ubuntu-latest
+    outputs:
+      has_label: ${{ steps.check-labels.outputs.result }}
+    steps:
+    - name: Check if label is present
+      id: check-labels
+      uses: actions/github-script@v3
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        script: |
+          const labels = context.payload.pull_request.labels.map(label => label.name);
+          if (labels.includes('documentation')) {
+            return true;
+          }
+
+          // Fetch the list of files changed in the PR
+          const { data: files } = await github.pulls.listFiles({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            pull_number: context.issue.number
+          });
+
+          // Check if any file is within the 'docs' folder
+          const docsChanged = files.some(file => file.filename.startsWith('docs/'));
+          return docsChanged;
+    
+    - name: Add label if not present
+      if: steps.check-labels.outputs.result == 'true'
+      uses: actions/github-script@v3
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        script: |
+          const labels = context.payload.pull_request.labels.map(label => label.name);
+          if (!labels.includes('documentation')) {
+            github.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              labels: ['documentation']
+            })
+          }
+
+  deploy_docs:
     runs-on: ubuntu-latest
     permissions:
       pull-requests: write
-    if: contains(github.event.pull_request.labels.*.name, 'documentation')
+    needs: add_label
+    if: needs.add_label.outputs.has_label == 'true'
     steps:
       - name: Checkout code
         uses: actions/checkout@v2

CONTRIBUTING.md

@@ -58,11 +58,11 @@ Generally, we want to only use the three primary types defined by the specificat
 
 - `feat:` - This should be the most used type, as most work we are doing in the project are new features. Commits using this type will always show up in the Changelog.
 - `fix:` - When fixing a bug, we should use this type. Commits using this type will always show up in the Changelog.
-- `chore:` - The least used type, these are **not** included in the Changelog unless they are breaking changes. But remain useful for an understandable commit history.
+- `chore:` - The least used type, these are __not__ included in the Changelog unless they are breaking changes. But remain useful for an understandable commit history.
 
 ### Conventional Commits: Breaking Changes
 
-Annotating **BREAKING CHANGES** is extremely important to our release process and versioning. To mark a commit as breaking, we add the `!` character after the type, but before the colon. For example:
+Annotating __BREAKING CHANGES__ is extremely important to our release process and versioning. To mark a commit as breaking, we add the `!` character after the type, but before the colon. For example:
 
 ```
 feat!: Rename nargo build to nargo check (#693)
@@ -94,10 +94,14 @@ The easiest way to do this is to have multiple Conventional Commits while you wo
 
 ### Reviews
 
-For any repository in the noir-lang organization, we require code review & approval by **one** Noir team member before the changes are merged, as enforced by GitHub branch protection. Non-breaking pull requests may be merged at any time. Breaking pull requests should only be merged when the team has general agreement of the changes and is preparing a breaking release.
+For any repository in the noir-lang organization, we require code review & approval by __one__ Noir team member before the changes are merged, as enforced by GitHub branch protection. Non-breaking pull requests may be merged at any time. Breaking pull requests should only be merged when the team has general agreement of the changes and is preparing a breaking release.
+
+If your Pull Request involves changes in the docs folder, please add the `documentation` flag and request an approval by a DevRel team member[^1]. An approval from DevRel is not necessary to merge your PR.
 
 ### With Breaking Changes
 
+Breaking changes need to be documented. Please ask for help from a DevRel[^1] team member if this is a problem for any reason. Breaking changes need a mandatory approval from DevRel.
+
 Sometimes, we don't merge pull requests with breaking changes immediately upon approval. Since a breaking change will cause Noir to bump to the next "minor" version, we might want to land some fixes in "patch" releases before we begin working on that next breaking version.
 
 ## Merging
@@ -156,6 +160,7 @@ Before merging, you should mentally review these questions:
 - Is continuous integration passing?
 - Do you have the required amount of approvals?
 - Does anyone else need to be pinged for thoughts?
+- Does it have changes to the docs? If so, did you request an approval from a DevRel[^1] team member?
 - Will this cause problems for our release schedule? For example: maybe a patch release still needs to be published.
 - What details do we want to convey to users in the Changelog?
 
@@ -167,11 +172,34 @@ Release Please parses Conventional Commit messages and opens (or updates) a pull
 
 When we are ready to release the version, we approve and squash the release pull request into `master`. Release Please will detect this merge and generate the appropriate tags for the release. Additional release steps may be triggered inside the GitHub Action to automate other parts of the release process.
 
+### Documentation releases
+
+We aim to have every documentation version matching the versions of Noir. However, to avoid unnecessary build time and size to the existent documentation, they aren't currently released alongside the stable releases, and instead are released ad-hoc.
+
+Please contact any member of the DevRel[^1] team if you believe a new docs version should be cut.
+
+### Cutting a new version of the docs
+
+The Noir documentation is versioned according to the [Docusaurus documentation](https://docusaurus.io/docs/versioning). In the `versioned_docs` and `versioned_sidebar` folders you will find the docs and configs for the previous versions. If any change needs to be made to older versions, please do them in this folder.
+
+In the docs folder, you'll find the current, unreleased version, which we call `dev`. Any change in this folder will be reflected in the next release of the documentation.
+
+While the versioning is intended to be managed by the core maintainers, we feel it's important for external contributors to understand why and how is it maintained. To bump to a new version, run the following command, replacing with the intended version:
+
+```bash
+npm run docusaurus docs:version <new_version_tag>
+```
+
+This should create a new version by copying the docs folder and the sidebars.js file to the relevant folders, as well as adding this version to versions.json.
+
+You can then open a Pull Request according to the the [PR section](#pull-requests)
+
 ## Changelog
 
 Noir's Changelog is automatically managed by Release Please and informed by the Conventional Commits (as discussed above).
 
 Given the following commits:
+
 - `feat(syntax): Implement String data type (#123)`
 - `chore(ci): Use correct rust version`
 - `fix(optimizer): Compile Boolean to u1`
@@ -200,3 +228,5 @@ Release Please would generate add the following to the Changelog:
 
 * **optimizer:** Compile Boolean to u1
 ```
+
+[^1]: Currently, @critesjosh, @catmcgee and @signorecello. For Noir documentation, it is recommended to tag @signorecello

compiler/wasm/package.json

@@ -29,7 +29,6 @@
     "lint": "NODE_NO_WARNINGS=1 eslint . --ext .ts --ignore-path ./.eslintignore  --max-warnings 0",
     "build:nix": "nix build -L .#noir_wasm",
     "install:from:nix": "yarn clean && yarn build:nix && cp -rL ./result/noir_wasm/nodejs ./ && cp -rL ./result/noir_wasm/web ./"
-
   },
   "peerDependencies": {
     "@noir-lang/source-resolver": "workspace:*"

docs/README.md

@@ -9,20 +9,20 @@ generator.
 
 Interested in contributing to the docs?
 
-Check out the contributing guide [here](./CONTRIBUTING.md).
+Check out the contributing guide [here](../CONTRIBUTING.md).
 
 ## Development
 
 ### Installation
 
 ```
-$ yarn
+yarn
 ```
 
 ### Local Development
 
 ```
-$ yarn start
+yarn start
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are
@@ -31,7 +31,7 @@ reflected live without having to restart the server.
 ### Build
 
 ```
-$ yarn build
+yarn build
 ```
 
 This command generates static content into the `build` directory and can be served using any static

docs/docs/language_concepts/01_functions.md

@@ -40,6 +40,45 @@ fn foo(x : Field, y : pub Field) -> Field {
 Note that a `return` keyword is unneeded in this case - the last expression in a function's body is
 returned.
 
+## Main function
+
+If you're writing a binary, the `main` function is the starting point of your program. You can pass all types of expressions to it, as long as they have a fixed size at compile time:
+
+```rust
+fn main(x : Field) // this is fine: passing a Field
+fn main(x : [Field; 2]) // this is also fine: passing a Field with known size at compile-time
+fn main(x : (Field, bool)) // 👌: passing a (Field, bool) tuple means size 2
+fn main(x : str<5>) // this is fine, as long as you pass a string of size 5
+
+fn main(x : Vec<Field>) // can't compile, has variable size
+fn main(x : [Field]) // can't compile, has variable size
+fn main(....// i think you got it by now
+```
+
+Keep in mind [tests](../nargo/02_testing.md) don't differentiate between `main` and any other function. The following snippet passes tests, but won't compile or prove:
+
+```rust
+fn main(x : [Field]) {
+    assert(x[0] == 1);
+}
+
+#[test]
+fn test_one() {
+    main([1, 2]);
+}
+```
+
+```bash
+$ nargo test
+[testing] Running 1 test functions
+[testing] Testing test_one... ok
+[testing] All tests passed
+
+$ nargo check
+The application panicked (crashed).
+Message:  Cannot have variable sized arrays as a parameter to main
+```
+
 ## Call Expressions
 
 Calling a function in Noir is executed by using the function name and passing in the necessary

docs/docs/modules_packages_crates/workspaces.md

@@ -34,6 +34,6 @@ default-member = "crates/a"
 
 `default-member` indicates which package various commands process by default.
 
-Libraries can be defined in a workspace. We just don't have a way to consume libraries from inside a workspace as external dependencies right now.
+Libraries can be defined in a workspace. Inside a workspace, these are consumed as `{ path = "../to_lib" }` dependencies in Nargo.toml.
 
 Inside a workspace, these are consumed as `{ path = "../to_lib" }` dependencies in Nargo.toml.