Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

First shot at contributing rules #11

Closed
wants to merge 3 commits into from
Closed

First shot at contributing rules #11

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
79612a2
First shot at contributing rules
DavidBruant Aug 23, 2019
bbe7e5b
Fix typo
DavidBruant Aug 23, 2019
488bf65
Add note about code formatting
DavidBruant Aug 23, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions .github/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Contributing

This repository contains the Agoric's technical documentation

It is meant to work like a wiki

Here are a couple of rules to follow:
- The content must be written in **English**
- The content must be written in **markdown** (`.md` file extension)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I notice that some of our own documentation is *.rst rather than *.md . Should we suggest that contributions can/should be *.rst ? How do we decide when to use which?

Attn @katelynsills @Chris-Hibbert @tatyana0219 @btulloh

Copy link
Contributor Author

@DavidBruant DavidBruant Aug 23, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for reference, i don't have a strong intention on markdown, it's only a first proposition

I notice that some of our own documentation is *.rst

i hadn't noticed that, thanks for the info

The points i find positive about markdown are:

  • Easy to get started when you already know how to write with Microsoft Word (!), because text is valid markdown and paragraph are naturally understood
    • simple learning curve (heading levels, bold, underline, links)
  • Fairly popular (github/~Trello/~Slack), so lots of people are probably already familiar + there are lots of markdown-related resources on the web
  • Web-friendliness: there is a natural transformation from markdown to HTML (and it takes only minutes to transform a github repo with markdown files into a website)
  • complex layouts and styling are possible because HTML can be written inside markdown + it's easy to add CSS/JavaScript to a resource in markdown

From what i've understood, one downside of markdown is that it can be harder to work with when trying to write a book, but i don't have this experience myself, so i cannot expand on that

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MarkDown is certainly a reasonable place to start. Let's agree that that's what we're using for most purposes.

If we need to use something else for some purposes, or eventually change to a different standard, we'll deal with that then.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I created a follow-up issue on the *.rst files: #19

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll wait for @erights to come back from TC39 and if there is no urgent reason not to merge this PR, i'll merge it
And everything can be modified afterwards; a github repo is de facto a wiki

- Code samples should adhere to Agoric formatting rules. They can be found in the form of a [prettier config](https://github.com/Agoric/new-repo/blob/master/.prettierrc.json) and [eslint config](https://github.com/Agoric/new-repo/blob/master/.eslintrc.js)

If it's your first contribution, it will go through a [pull request](https://help.github.com/en/articles/about-pull-requests#about-pull-requests) process, that is, someone will need to review and accept your changes first

When you're trusted enough, you will be granted the right to modify the content directly

If you do not feel confident about the changes you want to make, you can always create a pull request and request a review

## Copyright

By [contributing through Github](https://help.github.com/en/articles/github-terms-of-service#6-contributions-under-repository-license), you have agreed that you contributions to this repository are licenced as this [repo's licence](/LICENSE) (Apache 2.0)