sharkdp/dbg-macro

Add contributing guidelines

DerekCresswell opened this issue · 3 comments

With the recent changes to tests I believe it would be very beneficial to add some guidelines to this repo for things like tests and documentation.
@sharkdp this should likely be your responsibility. It should make the PR process in this repo more stream lined.
We should have :

  • Test guidelines. How many tests should be added and to which files.
  • Documentation standards. What should be inline comments and what should be added to a wiki.
  • Perhaps an issue / PR template.

Thank you very much for your feedback.

So far, my projects have worked quite well without any contribution guidelines.

@sharkdp this should likely be your responsibility. It should make the PR process in this repo more stream lined.

What part didn't you like about the PR process? I'm happy for any kind of feedback!

Test guidelines. How many tests should be added and to which files.

As for "how many tests": that's really not something that I can answer in advance. That depends on the complexity of the feature that is to be tested.

As for "which files": There is a single file with unit tests (tests/basic.cpp) which is most relevant. I have just added a "Development" section to the README that goes into some detail.

Documentation standards. What should be inline comments and what should be added to a wiki.

Again, a difficult question to answer in advance. There is no wiki so far, and I don't think we need one for a small project like this.

* Perhaps an issue / PR template.

So far, I didn't have any trouble with the kind of issues/bug-reports we got. Issue templates often feel too restrictive. I wouldn't really know what to put there right now.

Well it would never hurt to have one.
It's fair I may be thinking too much into this, I just really enjoy this repo and want the best for it.

Obviously not everything can be outlined to a T but some can be given more of a structure. It's mainly the first two points I'm thinking about. A wiki is overkill but some consistency with what all needs comments could be nice. If this continues to become larger and grow in functionality than these things will become more useful, but perhaps the progress will stall soon and this request will be obsolete.
Close this issue if you want. : )
The dev section is a nice addition.

I just really enjoy this repo and want the best for it.

I'm glad you like it - Thank you for your contributions!

It's mainly the first two points I'm thinking about. A wiki is overkill but some consistency with what all needs comments could be nice. If this continues to become larger and grow in functionality than these things will become more useful, but perhaps the progress will stall soon and this request will be obsolete.

It's really hard to put into words. That's the main problem. I think that questions like "how many tests?" do not so much depend on the project, but rather on the feature that a certain PR is implementing. The best answer I could give would be "enough, but not too many" 😄

I'm going to close this for now, but I'm happy to come back to this, if we feel that there is a need for a guideline in the future.