Contributing

Note that the USACO Guide has a public Github Repository. See our docs for more information about contributing. Feel free to contribute by submitting issues and Pull Requests!

Please help fix some of the issues on our Github Repository!

Ways to Contribute

Some examples:

Lesson

• Convert lists of resources to tables (Plat / Advanced).
• Add missing descriptions for sections, modules, or resources.

  • All resources should have descriptions.
• Improve explanations for sample problems.

  • If starred resource or editorial already has a good explanation, no need to repeat it.
• Improve implementations.

  • Include code handling input & output.
  • Should be consistent across languages.
• Adding modules!

Problems

• Convert lists of problems to tables (Plat / Advanced).
• Fix problem difficulties and tags.
• Add problems that are good examples of the module topic (and remove those that are not).
• Adding official editorial links.

  • Those for USACO are automatically generated.
• Adding editorials.

  • If no editorial exists, or if existing editorial could be improved.
  • Or solution code in a different language, etc.

Writing Content

All modules are written in MDX (Markdown + JSX), with limited $\LaTeX$ support from KaTeX and some custom components. You can check how an .mdx file renders by pasting it in the live editor.

See the Content Documentation for more info.

Useful Links

• Markdown Cheat Sheet
• Markdown Table Generator
• StackEdit

  • nice markdown editor
  • supports Katex
• Sublime Text

  • .md syntax highlighting is fine, is also ok for .mdx
  • You can open a .mdx file and set syntax highlighting to be the same as .md with View -> Syntax -> Open all with current extension as ... -> Markdown -> Markdown.
• Obsidian

  • Markdown editor
  • Automatically compiles $\LaTeX$ (doesn't require an installation)

Adding a Solution

1. Fork the GitHub repository.

2. If it doesn't already exist, create a new mdx file in solutions including frontmatter, ex. the following in USACO jan17-cow-dance-show.mdx:

   ---
   id: usaco-690
   source: USACO Silver 2017 January
   title: Cow Dance Show
   author: Óscar Garries
   ---
   
   [Official Analysis](http://www.usaco.org/current/data/sol_cowdance_silver_jan17.html)
   
   ## Explanation
   
   (add explanation here ...)
   
   Use `\texttt{}` around variable names with length *greater than one*, like so. Place long equations on separate lines with display math, and use `\cdot` instead of `*` to denote multiplication.
   
   $$
   \texttt{arr}[i]=2\cdot (a+b+c+d+e)+\sum_{j=0}^{i-1}\texttt{arr}[j]
   $$
   
   Some additional text styles which you might consider using:
   
   http://latexref.xyz/Font-styles.html
   
   http://applied-r.com/latex-font-styles/
   
   $func(var)$
   
   $\textit{func(var)}$
   
   $\textrm{func(var)}$
   
   $\text{func(var)}$
   
   $\textsf{func(var)}$
   
   $\textbf{func(var)}$
   
   $\texttt{func(var)}$
   
   ## Implementation
   
   **Time Complexity:** $\mathcal{O}(N\log^2N)$
   
   ^ Format time complexity like this. Should appear outside of `<LanguageSection>` if it's the same for all implementations.
   
   <LanguageSection>
   
   <CPPSection>
   
   (add cpp code)
   
   </CPPSection>
   
   <PySection>
   
   (if you have Python code)
   
   </PySection>
   
   <JavaSection />
   
   {/*  if you have no Java code */}
   
   </LanguageSection>

   Keep file names and solution IDs consistent; namely, USACO IDs should correspond to the URL on usaco.org.

3. Add your implementation, following these conventions and the conventions below:

   • Use tabs to indent.

   • Lines should not exceed 80 characters.

   • Be consistent about formatting your code, unlike the following snippet. We don't care about which one you use (a+b or a + b), but pick one and stick with it!

     a,b = (0,1)
     print(a+b)
     print(a + b)

   It is not necessary to add an alternative implementation in the same language as the official analysis (unless the alternative implementation takes a different approach or is written better / differently from the official implementation).

4. In the module's .problems.json file (in this case, Binary_Search.problems.json), change the kind of the solutionMetadata field to internal and remove all other fields. Also add tags (if you want). If the problem is not in a module, you can add the problem to extraProblems.json.

   {
     "uniqueId": "usaco-690",
     "name": "Cow Dance Show",
     "url": "http://www.usaco.org/index.php?page=viewproblem2&cpid=690",
     "source": "Silver",
     "difficulty": "Easy",
     "isStarred": false,
     "tags": ["Binary Search", "Ordered Set"],
     "solutionMetadata": {
       "kind": "internal"
     }
   },

5. Check that both the module and the solution render properly using the live editor before submitting a pull request.

Code Conventions

Since code for the USACO Guide is contributed from several authors, code style will not be uniform. Of course, we still strive for code that is readable and understandable. If any code does not compile or is hard to read, please contact us.

Please read the following resource before contributing code (although you do not have to follow all of the recommendations):

#include <bits/stdc++.h> // see /general/running-code-locally
using namespace std;

using ll = long long;

using vi = vector<int>;
#define pb push_back
#define all(x) begin(x), end(x)
#define sz(x) (int)(x).size()