Editing first pass for CONTRIBUTING.md #28
Conversation
CONTRIBUTING.md
Outdated
| - Run `git checkout -b branch-name`, where `branch-name` is the name you want to give your local branch | ||
| * Do your work. | ||
| - Make changes to the `.yml` files as needed | ||
| * Run `make` to update generated files such as `schema.csv` and `schema.md` |
There was a problem hiding this comment.
There is no schema.md anymore. Perhaps we can just mention here that this will update the generated files.
This is probably also a good place to mention that the README is fully generated and data has to changed under docs.
CONTRIBUTING.md
Outdated
| * Do your work. | ||
| - Make changes to the `.yml` files as needed | ||
| * Run `make` to update generated files such as `schema.csv` and `schema.md` | ||
| * Commit your changes locally. |
There was a problem hiding this comment.
I wonder if we really still need that? The reason I put it here is that I hope not only people with Git experience Contribute. Perhaps we can mention here instead that contributions can also be done through opening a Github issue?
There was a problem hiding this comment.
Git can be intimidating. Unless this is misleading or wrong, it's good to have it in there--especially if you want to invite new people to contribute. Experienced users can scan the list and keep going.
I added an "Other ways to contribute" section based on your comment about inviting contributors who are not experienced with Git. (Will be there next time I push.) Let me know what you think.
CONTRIBUTING.md
Outdated
| @@ -52,22 +66,47 @@ The structure of the of each document looks as following: | |||
| phase: 0 | |||
| ``` | |||
|
|
|||
| Each namespace has it's own file to keep the files itself small. Each namespace contains a list of fields which has all the fields inside. `title` and `description` are used to describe the namespace. `level` is for pure sorting purpose in the documentation output. | |||
| Each namespace has its own file. The fields for each namespace are stored in the file. `title` and `description` describe the namespace. `level` is for sorting in the documentation output. | |||
There was a problem hiding this comment.
We should remove all mentions of namespace here and replace it by prefix.
CONTRIBUTING.md
Outdated
| The `type` is the [Elasticsearch field type](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html). | ||
| `description` adds details about the field. | ||
| `example` adds an sample value. | ||
| The `phase` field indicates the development status of the field. If `phase` is left out, the default is 0. See |
There was a problem hiding this comment.
We now also added footnote. We should mention that here too.
CONTRIBUTING.md
Outdated
| * Go to the ECS repo: https://github.com/elastic/ecs | ||
| * Click `Issues` in the nav bar under the repo name. | ||
| * Click `New issue`. | ||
| * Add your text, and click `Submit new issue`. | ||
|
|
There was a problem hiding this comment.
@ruflin I added an "Other ways to contribute" section based on your comment about encouraging inexperienced Git users to contribute. Let me know what you think.
Are there any other guidelines or requirements (other than what are in this document) that we want to suggest for submitting issues?
CONTRIBUTING.md
Outdated
| * Go to the ECS repo: https://github.com/elastic/ecs | ||
| * Click `Issues` in the nav bar under the repo name. | ||
| * Click `New issue`. | ||
| * Add your text, and click `Submit new issue`. |
There was a problem hiding this comment.
Let's add a note here that users should provide as many details as possible in the description of an issue. Sounds obvious but ...
|
|
||
|
|
||
| ## Requirements | ||
|
|
||
| To contribute to ECS the following tools are expected to be running on your machine: | ||
| You need these tools to contribute to ECS: | ||
|
|
||
| * [Git](https://git-scm.com/) | ||
| * [Python](https://www.python.org/) | ||
| * [Go](https://golang.org/) | ||
|
|
||
| ## Steps to contribute |
There was a problem hiding this comment.
Should we have a main title Contribute and below the two ways. Not sure yet how we should call the two. Ideas?
There was a problem hiding this comment.
I was thinking of "Steps to contribute" as the preferred (main) path for people who are capable of contributing through a PR, with "Other ways to contribute" as an alternate (if...else) path. That's why I formatted "Other ways" as a subheading to "Steps...".
If you feel strongly that contributing through a PR and contributing through an issue should be at the same level heading, I will make that happen.
There was a problem hiding this comment.
I'm on the fence about this one. For code parts I like PR's directly as they make discussing easier. But this is not really code and often an issue is the right part to get started as it's more question based initially.
But in the end I don't think it will make a real difference on what we call it here. So let's move forward with the way it is.
There was a problem hiding this comment.
Thanks for taking time to explain. Your insights help me understand the project better, and will help me add more value going forward.
Summary: