Update community-facing contribution documentation [skip ci]#8137
Update community-facing contribution documentation [skip ci]#8137zjs merged 4 commits intovmware:masterfrom
Conversation
Much of the documentation about contributing to the project was out- of-date, incomplete, or inaccurate. Update it to reflect current best practices.
Begin to update process documentation for issue management.
CONTRIBUTING.md
Outdated
| If you need to squash changes into an earlier commit, you can use: | ||
| Writing code that is easy to understand, debug, and modify is important to the | ||
| long-term health of a project. To help achieve these goals, we have adopted | ||
| coding style recommendations of the boarder software community. |
CONTRIBUTING.md
Outdated
| pull request. | ||
|
|
||
| Automated testing uses [Drone][dronesrc]. | ||
| You can use the `--fixup` and `--squah` options of `git commit` to communicate |
CONTRIBUTING.md
Outdated
| - To specify a specific datastore you want, use `[shared datastore=nfs-datastore]`. | ||
| - To make normal failures fatal during integration testing, use `[fast fail]`. | ||
| - To specify a specific datastore, use `[shared datastore=nfs-datastore]`. | ||
| - To specify the number of parallel jobs you want, use `[parallel jobs=2]`. |
There was a problem hiding this comment.
These directives are in the PR template in the comments for reference - this comment must be deleted or the directives within the comment are utilized.
CONTRIBUTING.md
Outdated
| of the `vmware` organization in GitHub. If this occurs, leave a comment on your | ||
| pull request asking that the build be restarted by an organization member. | ||
|
|
||
| To skip membership checking when restarting a build: |
There was a problem hiding this comment.
when and why would you do this? I assume this is linked to the not above about being a member but it's not completely evident.
CONTRIBUTING.md
Outdated
| should include specific details about what is (or isn't happening). | ||
|
|
||
| Proactively including screenshots and logs can be very helpful. When including | ||
| logs, please ensure that formatting is preserved by using [code blocks][code]. |
There was a problem hiding this comment.
When including log snippets inline in the PR instead of as an attachment, please ensure ...
Maybe we need a link to how to collect container log bundles - and possibly a note about using debug=1 if the issue can be recreated.
There was a problem hiding this comment.
Maybe we need a link to how to collect container log bundles - and possibly a note about using debug=1 if the issue can be recreated.
This feels like the wrong place for that sort of guidance — unless we want to simply link to the relevant section(s) of the user-facing documentation.
There was a problem hiding this comment.
I think you're correct. A link would suffice, or we can omit it and request on a case-by-case basis as needed. No change needed in this PR.
| Integration tests require a running ESX on which to deploy VIC Engine. See [VIC Integration & Functional Test Suite](tests/README.md). | ||
| We use [ZenHub][zenhub] for project management on top of GitHub issues. Boards | ||
| can be viewed [via the ZenHub website][board-zenhub] or, once you have installed | ||
| the [brower extension][zenhub-plugin], directly [within GitHub][board-github]. |
There was a problem hiding this comment.
If using a browser that does not have a plugin, the board can be accessed directly via the zenhub site.
There was a problem hiding this comment.
I'm not quite sure what change you're suggesting here? Just re-ordering the references to the board within GitHub and the board on the ZenHub website?
There was a problem hiding this comment.
I'm not actually sure what I'm suggesting here either. Reading it again there is no reason for this comment. Either I failed to read it correctly the first time around or it changed before I submitted the comment. Comment retracted.
4 participants
Much of the documentation about contributing to the project was out-of-date, incomplete, or inaccurate. Update it to reflect current best practices.
This PR does not attempt to completely revise information about the issue management process.