Skip to content

Updating contribution guides for docs. #325

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

Merged
merged 30 commits into from
May 21, 2019
Merged

Updating contribution guides for docs. #325

Show file tree
Hide file tree
Changes from 14 commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
2c8a4c3
Merge pull request #306 from magento/develop
KevinBKozan Jan 29, 2019
b4002b3
Merge pull request #311 from magento/develop
KevinBKozan Feb 19, 2019
6c9c34d
Updating contribution guides for docs.
dobooth Apr 1, 2019
ef7a76e
Merge branch 'develop' into db_contributions
dobooth Apr 1, 2019
06d2e91
Merge branch 'develop' of github.com:magento/magento2-functional-test…
dobooth Apr 2, 2019
0c43a9e
Update .github/CONTRIBUTING.md
dshevtsov Apr 2, 2019
5569b0a
Update .github/DOCUMENTATION_TEMPLATE.md
dshevtsov Apr 2, 2019
2cc5666
Update .github/DOCUMENTATION_TEMPLATE.md
dshevtsov Apr 2, 2019
2290e2e
Fixes per review.
dobooth Apr 2, 2019
a6786ee
Update .github/DOCUMENTATION_TEMPLATE.md
dshevtsov Apr 2, 2019
a0faa1d
Update .github/DOCUMENTATION_TEMPLATE.md
dshevtsov Apr 2, 2019
5f27f40
Update .github/DOCUMENTATION_TEMPLATE.md
dshevtsov Apr 2, 2019
acc9238
Update .github/DOCUMENTATION_TEMPLATE.md
dshevtsov Apr 2, 2019
978d945
Update .github/DOCUMENTATION_TEMPLATE.md
dshevtsov Apr 2, 2019
6182ec9
Update .github/DOCUMENTATION_TEMPLATE.md
dshevtsov Apr 2, 2019
447ed0f
More review fixes.
dobooth Apr 2, 2019
2099d30
Fixed link.
dobooth Apr 2, 2019
9c68e7d
Fixed header
dobooth Apr 2, 2019
539a562
Merge branch 'master' into db_contributions
dobooth Apr 5, 2019
9501614
Fixes per review.
dobooth Apr 5, 2019
d0fd11b
Cleaned up header
dobooth Apr 15, 2019
b9d2459
Merge branch 'develop' into db_contributions
dobooth Apr 15, 2019
0b23734
Grammar fix.
dobooth Apr 16, 2019
70e59a5
Fixed grammar.
dobooth Apr 22, 2019
2eef763
Indenting so markdown syntax shows.
dobooth Apr 29, 2019
42bc8d1
Indenting so markdown syntax shows.
dobooth Apr 29, 2019
51d66eb
Linked to Basic Template.
dobooth Apr 29, 2019
8c7c139
Update .github/DOCUMENTATION_TEMPLATE.md
dobooth May 21, 2019
f03a564
Update .github/DOCUMENTATION_TEMPLATE.md
dobooth May 21, 2019
eaa1d0e
Merge branch 'develop' into db_contributions
dobooth May 21, 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
6 changes: 3 additions & 3 deletions .github/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ All contributors are required to submit a click-through form to agree to the ter

- Unit/integration test coverage
- Proposed documentation update.
For the documentation contribution guidelines, see [DevDocs Contributing][devdocs].
For the documentation contribution guidelines, see [DOCUMENTATION_TEMPLATE][].
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
For the documentation contribution guidelines, see [DOCUMENTATION_TEMPLATE][].
For the documentation contribution guidelines, see [documentation template][].

No need to use code-like letter case because it is not related to a file name or any other entity unless it is intended to be a reference for DOCUMENTATION_TEMPLATE.md.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

It is a ref to it.

Copy link
Contributor

@dshevtsov dshevtsov Apr 2, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

no, it refers to .../.github/CONTRIBUTING.md in link definitions

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Fixed.

7. For large features or changes, [open an issue][issue] to discuss first.
This may prevent duplicate or unnecessary effort, and it may gain you some additional contributors.
8. To report a bug, [open an issue][issue], and follow [guidelines about bugfix issues][issue reporting].
Expand Down Expand Up @@ -160,7 +160,7 @@ Label| Description
[create issue]: https://help.github.com/articles/creating-an-issue/
[create pr]: https://help.github.com/articles/creating-a-pull-request/
[Definition of Done]: https://devdocs.magento.com/guides/v2.2/contributor-guide/contributing_dod.html
[devdocs]: https://github.com/magento/devdocs/blob/master/.github/CONTRIBUTING.html
[DOCUMENTATION_TEMPLATE]: https://github.com/magento/devdocs/blob/master/.github/DOCUMENTATION_TEMPLATE.md
[existing issues]: https://github.com/magento/magento2-functional-testing-framework/issues?q=is%3Aopen+is%3Aissue
[existing PRs]: https://github.com/magento/magento2-functional-testing-framework/pulls?q=is%3Aopen+is%3Apr
[GitHub documentation]: https://help.github.com/articles/syncing-a-fork
Expand All @@ -171,4 +171,4 @@ Label| Description
[Magento Contributor Agreement]: http://www.magento.com/legaldocuments/mca
[MFTF repository]: https://github.com/magento/magento2-functional-testing-framework
[open new issue]: https://github.com/magento/magento2-functional-testing-framework/issues/new
[Travis CI]: https://travis-ci.com/magento/magento2-functional-testing-framework/pull_requests
[Travis CI]: https://travis-ci.com/magento/magento2-functional-testing-framework/pull_requests
65 changes: 65 additions & 0 deletions .github/DOCUMENTATION_TEMPLATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# How to conttribute to MFTF docs

MFTF documentation is kept within the /docs/ folder in this repository.
We welcome contributions to the documentation.
This page describes the process for submitting documentation and serves as a template for a properly written content.

The contribution workflow for the Magento functional testing framework (MFTF) documentation is the same as submitting code.

1. Make a branch from the `develop` branch in the [MFTF repo][].
1. Make edits/additions/deletions as needed.
1. Submit your PR to the `develop` branch.

Once submitted, a member of the documentation team will review and merge it.
We will inform you if it needs any additional processing.

Any changes to the Table of Contents will need to be made in the regular [devdocs repo][].
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
Any changes to the Table of Contents will need to be made in the regular [devdocs repo][].

I think table of contents on devdocs should not be a part of this generic documentation guidelines.
It is job of devdocs contributors. We can add this details later if mftf contributors would request for it.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Going to leave it in.

Copy link
Contributor

@dshevtsov dshevtsov Apr 2, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

Then, you should mention that the documentation is also published on DevDocs website, because it is not clear what Table of Contents you refer to. And that to keep the table of contents consistent, the contributor will need to add the corresponding changes to the devdocs repository.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Explained and linked to the TOC.

Copy link
Contributor

Choose a reason for hiding this comment

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

I don't see the changes.


## H2 Heading - blank line before and after, capitalize first word only

Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
## Ordered lists

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Added.

## Ordered lists

1. Number all ordered list items as `1.`
1. Single spafce after the number.
1. Blank line before and after list.

## Unordered lists

- Use dashes in unordered lists.
- Add one space after the dash.
- Add a blank line before and after list.

## Code samples

For code highlighting, wrap code samples in the following format:

```xml
<xmlSample>
...
...
</xmlSample>
```

Replace the `xml` with the corresponding language (tupe) of the code sample. Use `bash` for shell commands and `terminal` for terminal output.

## Markdown tables

| Header | Header |
| ----------- | ----------- |
| Colume 1 text | Column 2 text|
| Column 1 text | Column 2 text|

Markdown formatting works for simple tables. It does not support multiline content within a cell, or split/merged cells within a row or column.

## Other tips

- Use spaces instead of tabs.
- Do not duplicate blank lines.
- Read more about how to [Contribute to Magento Devdocs][]

<!-- For readability, we abstract the link URLS to the bottom of the page. The extra set of square brackets denotes it is a link, rather than plain brackets. >

<!-- Link Definitions -->
[devdocs repo]: https://github.com/magento/devdocs
[MFTF repo]: https://github.com/magento/magento2-functional-testing-framework
[Contribute to Magento Devdocs]: https://github.com/magento/devdocs/blob/master/.github/CONTRIBUTING.md