martinmo
commented
5 months ago I'm only wondering why we now have two documents, and how developers will know what document to read for which purpose. I have the feeling that they need to read both documents anyway in order to do meaningful work. Can they be merged in a reasonable way?
The other document specializes on the RFC keywords and without a complete restructuring I didn't see how I could fit my topics in there. For this reason, I decided to create a separate document. The new document can be seen as the more general entrypoint which a newcomer should read first.
I agree with you that this isn't obvious at the moment. One more thing which isn't obvious: the testing related contributor documents are currently placed below the "operations" hierarchy:
contributor-docs/
├── index.md
└── operations/
├── iam/
│ ├── identity-federation-in-scs.md
│ └── openstack-federation-via-oidc.md
├── operations/
│ └── zuul-ci-cd-quickstart-user-guide.md
└── tests/
├── rfc2119-keyword-test-guide.md
└── test-implementation-guide.mdMy suggestion: create a new "development" hierarchy and move "tests" there. Furthermore, solve the "which document to read first?" question by putting an index.md with an appropriate overview in there. So it will look like this:
contributor-docs/
├── development/
│ ├── index.md
│ └── tests/
│ ├── rfc2119-keyword-test-guide.md
│ └── test-implementation-guide.md
├── index.md
└── operations/
├── iam/
│ ├── identity-federation-in-scs.md
│ └── openstack-federation-via-oidc.md
└── operations/
└── zuul-ci-cd-quickstart-user-guide.md@mbuechse what do you think about this proposal?
I extended the test guidelines with information on how to write unit/regression tests. Furthermore, I added hints/links to other important information for tests authors, most importantly: the existing RFC keywords guide and the assumption about privileges.
Resolves: #185