Skip to content

Commit cf74ca1

Browse files
VasilyStrelyaevVasilyStrelyaev
authored
[docs] Update the contribution guide to reflect changes in the docs workflow (DevExpress#3067)
* Update the contribution guide to reflect changes in the documentation workflow * Apply Helen's correction no. 1 Co-Authored-By: VasilyStrelyaev <[email protected]> * Apply Helen's correction no. 2 Co-Authored-By: VasilyStrelyaev <[email protected]> * Update CONTRIBUTING.md * Fix 'find a problem' * Dirk's corrections
1 parent d7b97e6 commit cf74ca1

File tree

1 file changed

+78
-15
lines changed

1 file changed

+78
-15
lines changed

Diff for: ‎CONTRIBUTING.md

+78-15
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,37 @@
11
# Contributing to TestCafe
22

3-
TestCafe would not be possible without active support from the community. We certainly appreciate and would
4-
encourage your contributions, no matter how large or small.
3+
TestCafe would not be possible without active support from the community. We appreciate and encourage your contributions, no matter how big or small.
54

6-
To that end, please review our contribution guidelines first.
5+
Review our contribution guidelines:
76

87
* [Code of Conduct](#code-of-conduct)
98
* [General Discussion](#general-discussion)
109
* [Reporting a Problem](#reporting-a-problem)
1110
* [Code Contribution](#code-contribution)
11+
* [Contribute to Documentation](#contribute-to-documentation)
12+
* [Documentation for the Current Functionality](#documentation-for-the-current-functionality)
13+
* [Documentation for New Features](#documentation-for-new-features)
1214

1315
## Code of Conduct
1416

15-
TestCafe has adopted a [Contributor Code of Conduct](CODE_OF_CONDUCT.md), abide by its terms.
17+
TestCafe abides by the [Contributor Code of Conduct](CODE_OF_CONDUCT.md).
1618

1719
## General Discussion
1820

1921
Join the TestCafe community on Stack Overflow: ask and answer [questions with the TestCafe tag](https://stackoverflow.com/questions/tagged/testcafe).
2022

2123
## Reporting a Problem
2224

23-
If you find a problem when using TestCafe, please file an issue in our [GitHub repository](https://github.com/DevExpress/testcafe/issues).
24-
However, to save some time, please search through the existing issues to see if the problem has already been reported or addressed.
25+
If you encounter a bug when using TestCafe, please file an issue in our [GitHub repository](https://github.com/DevExpress/testcafe/issues).
26+
We recommend searching through the existing issues to see if the problem has already been reported or addressed.
2527

26-
When you create a new issue, template text is automatically added to its body. To help us understand the issue you're describing, be sure to fill in all sections in this template. We process issues with insufficient details after all the others, which may take significant time without any guarantees.
28+
When you create a new issue, the template text is automatically added to its body. You should complete all the sections in this template to help us understand the issue you are describing. Missing information could delay the processing time.
2729

2830
## Code Contribution
2931

30-
Please follow the steps below when submitting your code.
32+
Follow the steps below when submitting your code.
3133

32-
1. Search the [list of issues](https://github.com/DevExpress/testcafe/issues) to see if there
33-
is an issue for the bug or feature you are going to work on. If you do not find one, please create your own.
34+
1. Search the [list of issues](https://github.com/DevExpress/testcafe/issues) to see if there is an issue for the bug or feature you are going to work on or create a new one.
3435

3536
2. If you are going to address an existing issue, check the comment thread to make sure that nobody is working on it at the moment.
3637

@@ -39,9 +40,9 @@ Please follow the steps below when submitting your code.
3940
4. Core team members may need to discuss the details of the proposed fix with you. As soon as you get the green light from them,
4041
leave a comment saying that you are currently working on this issue.
4142

42-
5. Fork TestCafe and create a branch in your fork. Name this branch with an issue number, e.g. `gh852`, `gh853`.
43+
5. Fork TestCafe and create a branch in your fork. Name this branch with an issue number, for example `gh852`, `gh853`.
4344

44-
> If you are going to update the documentation, do this in a separate branch, e.g. `gh852-docs`.
45+
> If you are going to update the documentation follow the steps described in [Contribute to Documentation](#contribute-to-documentation).
4546
4647
6. Commit your changes into the branch.
4748

@@ -61,11 +62,73 @@ Please follow the steps below when submitting your code.
6162

6263
10. Push changes to your fork.
6364

64-
11. Submit a pull request. If you are also updating the documentation, submit a separate pull request for these changes.
65+
11. Submit a pull request. If you are also updating the documentation, submit a separate pull request as described in [Contribute to Documentation](#contribute-to-documentation).
6566

6667
The pull request name should describe what has been done and contain
6768
the [closes](https://github.com/blog/1506-closing-issues-via-pull-requests) directive
6869
with an appropriate issue number.
6970

70-
Documentation pull requests should have the `[docs]` prefix in their title.
71-
This ensures that documentation tests are triggered against these pull requests.
71+
## Contribute to Documentation
72+
73+
### Documentation for the Current Functionality
74+
75+
If you want to fix a bug in the current documentation or make an enhancement that relates to the existing functionality, follow the instructions below.
76+
77+
1. Fork TestCafe and create a branch in your fork. Name this branch with an issue number followed by the `docs` postfix, e.g. `gh852-docs`.
78+
79+
2. Commit your changes into the branch.
80+
81+
> Note that links in the documentation should point to `.md` files in the repository, so that the documentation is browsable on GitHub. When the website is built, all links are automatically modified to HTML links.
82+
83+
3. Fetch upstream changes and rebase your branch onto `master`.
84+
85+
4. Run tests before submitting a pull request to ensure that Markdown is styled properly and there is no broken links.
86+
87+
```sh
88+
gulp test-website
89+
```
90+
91+
5. Push changes to your fork.
92+
93+
6. Submit a pull request. Documentation pull requests should have the `[docs]` prefix in their title. This ensures that documentation tests are triggered against these pull requests.
94+
95+
### Documentation for New Features
96+
97+
Documentation for new features is written in a separate branch `new-docs`.
98+
99+
Do the following to fetch this branch and commit to it.
100+
101+
1. Fork TestCafe.
102+
103+
2. Download the `new-docs` branch to your local repository and perform check-out.
104+
105+
```sh
106+
git fetch upstream new-docs:new-docs
107+
git checkout new-docs
108+
```
109+
110+
3. Set the local branch to track the remote `new-docs` branch.
111+
112+
```sh
113+
git branch -u upstream/new-docs
114+
```
115+
116+
4. Create a new branch at the top of `new-docs`.
117+
118+
```sh
119+
git checkout -b new-branch new-docs
120+
```
121+
122+
5. Commit your changes into this branch.
123+
124+
> Note that links in the documentation should point to `.md` files in the repository, so that the documentation is browsable on GitHub. When the website is built, all links are automatically modified to HTML links.
125+
126+
6. Run tests before submitting a pull request to ensure that Markdown is styled properly and there is no broken links.
127+
128+
```sh
129+
gulp test-website
130+
```
131+
132+
7. Push changes to your fork.
133+
134+
8. Open a pull request against `DevExpress:new-docs`. Documentation pull requests should have the `[docs]` prefix in their title. This ensures that documentation tests are triggered against these pull requests.

0 commit comments

Comments
 (0)