Skip to content

Commit 4612817

Browse files
author
Liz
committed
Add contributing guide.
1 parent 07cb094 commit 4612817

File tree

1 file changed

+92
-0
lines changed

1 file changed

+92
-0
lines changed

CONTRIBUTING.md

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
2+
# Guide to Contributing
3+
4+
The Algorand docs repository hosts Algorand’s core developer documentation. This content is served directly to the Algorand Developer Portal under the Docs section located here: [Algorand Developer Docs](https://developer.algorand.org/docs/).
5+
6+
## Who We Are
7+
8+
The Algorand technical documentation repository is managed by the Algorand Docs Team which is composed of members from the Developer Relations, Engineering, and Product teams at Algorand Inc.
9+
10+
<a id="charter"></a>**Our Charter**
11+
12+
We work closely and tirelessly with the core Algorand Development Team to produce and present accurate, comprehensive, and up-to-date technical documentation to support the best developer experience on Algorand.
13+
14+
<a id="tenets"></a>**Our Tenets**
15+
16+
* Provide all the building blocks of technical information necessary for developers to build applications or run nodes on Algorand.
17+
* Be the most objective source of technical information.
18+
* Write clear prose and code to swiftly deliver new concepts to all developers.
19+
20+
## Types of Contributions
21+
As members of an open source project we welcome community contributions in the following ways.
22+
23+
### Fixing Errors or Inaccuracies
24+
The Algorand protocol and SDKs are constantly updated with new features that we do our best to stay ahead of, but sometimes portions of our documentation may become out of date. Sometimes we just make mistakes. If you come across typos, code errors, or information that is inaccurate, we encourage you to [log an issue](#how-to-file-an-issue) or correct it through a [pull request](#how-to-create-a-pull-request).
25+
26+
[**Issue Template**](https://github.com/algorand/docs/issues/new?assignees=&labels=minor+update&template=fixing-errors-or-inaccuracies.md&title=)
27+
28+
### Small Improvements for Clarity of Message
29+
We recognize that there may be a clearer way to explain a concept or write a snippet of code and we welcome contributions that can make these improvements on our behalf.
30+
31+
However, keep in mind that improvements can often be subjective and in order to keep capacity available for more critical documentation updates, we will not spend significant time discussing an improvement if the value add is not immediately apparent. We will reconsider these cases with the addition of more objective data points such as if a diverse representation of the developer community upvotes a particular issue or PR.
32+
33+
[**Issue Template**](https://github.com/algorand/docs/issues/new?assignees=&labels=&template=small-improvements-for-clarity-of-message.md&title=)
34+
35+
### Large Additions or Modifications
36+
The Algorand technical documentation is intimately tied to updates in [go-algorand](https://github.com/algorand/go-algorand), our SDKs, and other open source developer tools found [here](https://github.com/algorand). Strategic planning on how to present the information that accompanies feature updates within the context of the entire developer experience is the primary charter of the Algorand Docs team, and it may be difficult for a community member to acquire the same level of context. Therefore, we strongly encourage you to [log an issue](#how-to-file-an-issue) that falls under this category _before_ contributing through a pull request to avoid wasted effort on your part. Similar to the above section, we will prioritize handling cases that show significant interest or support from a diverse representation of the developer community through issue upvoting.
37+
38+
[**Issue Template**](https://github.com/algorand/docs/issues/new?assignees=&labels=&template=large-additions-or-modifications.md&title=)
39+
40+
#### Tutorial and Solution Submissions
41+
If you have a step-by-step guide for developers or sample application code, we encourage you to [submit it](https://developer.algorand.org/pages/submissions/) as a [Tutorial](https://developer.algorand.org/tutorials/) or [Solution](https://developer.algorand.org/solutions/), respectively, on the [Algorand Developer Portal](https://developer.algorand.org/). Tutorials and Solutions can be more personalized and do not follow the same [charter](#charter) and [tenets](#tenets) as the documentation. View the Style Guide for Tutorials and Solutions [here](https://developer.algorand.org/pages/style-guide).
42+
43+
### Community Projects
44+
Finally, if you developed a tool or application that would benefit members of the Algorand community, feel free to submit a PR updating the [Community Projects](./docs/community.md) page. Include the name of your project, a logo, and description under the appropriate Project category. If your category does not exist, please suggest a header and we can update as needed through the PR process.
45+
46+
The Community page is displayed [here](https://developer.algorand.org/docs/community/) in production.
47+
48+
## How to File an Issue
49+
First search [open issues](https://github.com/algorand/docs/issues) to make sure the issue has not been filed already. If it has not, open a new issue using one of the following three templates or Other, if your request does not fall into any of these categories:
50+
51+
1. [Fixing Errors and Inaccuracies](https://github.com/algorand/docs/issues/new?assignees=&labels=minor+update&template=fixing-errors-or-inaccuracies.md&title=)
52+
2. [Small Improvements for Clarity of Message](https://github.com/algorand/docs/issues/new?assignees=&labels=&template=large-additions-or-modifications.md&title=)
53+
3. [Large Additions or Modifications](https://github.com/algorand/docs/issues/new?assignees=&labels=&template=large-additions-or-modifications.md&title=)
54+
55+
56+
## How to Create a Pull Request
57+
58+
First read the [Types of Contributions](#types-of-contributions) section to make sure a pull request is the best option for your contribution. If so, fork this repo, and initiate your pull request against the `staging` branch following the general process described [here](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork). Make sure to [test your changes](#testing-changes) before submitting. After a pull request is submitted, the docs team will review it and communicate through the comments section of the PR.
59+
60+
Approved changes will be merged into `staging` and periodically merged into `master` at which point it will be visible on the Algorand Developer Portal.
61+
62+
### Testing Changes
63+
64+
We use [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) as the static site generator with several activated plugins that can be found in the [mkdocs.yml](./mkdocs.yml) file.
65+
66+
Run the documentation locally in a web browser to test how your changes will render. The local theme is an out-of-the-box Material theme, which is not exactly what it will look like on the website where we apply our own theme to match the rest of the Developer Portal. However, it should be close enough to determine whether or not your changes will result in formatting errors.
67+
68+
To run locally:
69+
70+
From within the root `docs` directory.
71+
72+
Make sure you have all dependencies installed:
73+
74+
```bash
75+
$ pip3 install -r requirements.txt
76+
```
77+
78+
Run mkdocs and serve the content in your local browser:
79+
80+
```bash
81+
$ mkdocs serve
82+
```
83+
84+
View the docs in your web browser: [http://localhost:8000/](http://localhost:8000/)
85+
86+
87+
88+
## Code of Conduct
89+
90+
See [here](./CODE_OF_CONDUCT.md).
91+
92+

0 commit comments

Comments
 (0)