###### tags: `Documentation and Standardization` ## General suggestions - [Example rendered pdf.](https://github.com/spearbit/portfolio/blob/master/pdfs/Morpho-Av3-Spearbit-Security-Review.pdf) - **Avoid first/second person tenses**. Avoid starting and using sentences such as "I think", "I agree", "he said", etc... - **Avoid using `#`.** Make sure there aren't any `#`s written in the Issue description. - **The issue description should be detailed.** Ideally, someone who is outside of the project and the security review team should be able to understand the issues, merely by reading the issue description. - **Group issues together**, whenever that's relevant. For example, if a certain gas optimization is relevant throughout the codebase, keep it as a single issue. - **Avoid screenshots.** Prefer text whenever possible, for example, for code snippets, specification, etc. - **Consider minimizing code examples** for the most relevant parts. - **Use permalinks** for links to a hosted git source code (to specific commit hashes). - **Avoid raw links**, i.e, prefer [`NoDelegateCall.sol#L18`](https://github.com/Uniswap/v3-core/blob/62d65bf88c4fb23671104c28f5bcae566274cb15/contracts/NoDelegateCall.sol#L18) instead of https://github.com/Uniswap/v3-core/blob/62d65bf88c4fb23671104c28f5bcae566274cb15/contracts/NoDelegateCall.sol#L18. - **Consider using diffs** while making code recommendations. - **Use code text to highlight any references to code** (function names, variable names, etc.) i.e. denoted with backticks `variable` vs variable. - **Do not leave fields blank**. If the **Project:...** and/or **Spearbit:...** fields are empty or there is nothing significant to add, simply write the issue status for both fields. <br> ## Specific suggestions Make sure that... **1. There aren't any grammar mistakes. e.g., use the grammarly extension.** **2. The format is correct for each section and starts on the same line:** ```diff - **Description:** - The `AssemblyLib` is using non-full word ... + **Description:** The `AssemblyLib` is using non-full word ... ``` **3. All hyperlinks are handled correctly, else it will break the report generator** ```diff - Fixed in https://github.com/ProtocolXYZ/v2/pull/319 + Fixed in [PR 319](https://github.com/ProtocolXYZ/v2/pull/319). ``` **4. Wrap variable names with backtics `''`** ```diff - signextend + `signextend` ``` **5. Complete the issue if its missing information, never leave it empty and confirm its label status (fixed or acknowledged). Use the protocol team's answers and/or ask them for one** ```diff - **ProtocolXYZ:** - **Spearbit:** + **ProtocolXYZ:** We have addressed the issue in [PR 319](https://github.com/ProtocolXYZ/v2/pull/319) + **Spearbit:** Fixed. OR + **ProtocolXYZ:** Acknowledged. + **Spearbit:** Acknowledged. ``` **6. Do not use hashtags in the issue body as it breaks markdown -> latex generation** ```diff - **Description:** Lorem ipsum .... - #### Proof Of Concept... + **Description:** Lorem ipsum .... + - Proof Of Concept... ``` <br> ## Examples #### 1: Good ![](https://hackmd.io/_uploads/r14MP6Zdn.png) #### Ex 2: Bad (modified for illustration purposes), terrible and incomplete formatting ![](https://hackmd.io/_uploads/SJY0KaZO3.png) #### Ex 2: Good ![](https://hackmd.io/_uploads/r1q4FpZu2.png) #### Ex 3: Bad, missing protocol team comments ![](https://hackmd.io/_uploads/rJaRbfgFh.png) #### Ex 3: Good ![](https://hackmd.io/_uploads/SyMbGfxFn.png)