[FEATURE]
GabriellyAssuncao opened this issue · 7 comments
Is your feature request related to a problem? Please describe.
Hello @wwahammy . As you know, @pedrohelias and I are contributing to Houdini. We are having some difficulties in understanding the issues, as we do not know the project in depth, we would like to propose contribution policies for the repository. If you agree, we'll do it quickly. If you have any other ideas that we can apply to make the community more accessible to new contributors, please don't hesitate to let us know!
Describe the solution you'd like
A clear and concise description of what you want to happen.
Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.
Additional context
Add any other context or screenshots about the feature request here.
Hi @GabriellyAssuncao and @pedrohelias. I'm open to that idea. What kind of contribution policies did you have in mind?
Hi @wwahammy , sorry for the late, the last 2 weeks were too hard for me. First, we thought in certain commits policies, like "tag" the issue that the commit refears to(e.g. # 1 - "commit text"). This technique will reference the issue with the #, and the commit text will briefly represent the idea behind the contribution. In my experience, I think it helps to identify and find some parts of code, and find problematics codes, too, if that is the case. Apart from the fact that it helps to identify issues that have already been worked on. This was a motivation for me to open this issue(#1462).
There is other policies that we think but we will evolving the idea better, before suggest to you. But, what you think about the new commit policie? If you allow this suggest, we will prepare the documentation about this(in English and Portuguese.). So, what you think?
Commit Policies
First Case
Commits are essential for tracking changes and additions to the project.
The imperative mode (assertive actions and orders) should be used to mention what was done.
If the commit concerns a simple issue, make the commit as follows:
git commit -m "#IdIssue - Message"
A case more complex
Due to its importance, if the commit concerns something more complex, use the following template for standardization, replacing the text of the comments '# will not be read in the commit':
. #Id-of-Issue - Commit title: start with capital letter, objective
# No more than 50 chars, this line has 50 #
#Skip line
# Body: Explain what and why
# No more than 72 characters (this line has) #
#OPTIONAL: If there is, include this line of co-authors of your commit for each contributor.
#Skip 2 lines
# Co-authored-by: name1 <user1@users.noreply.github.com>
# Co-authored-by: name2 <user2@users.noreply.github.com>
#Skip line
To use the template, add the template file .gitmessage, being in your local repository folder, at the root, as follows:
git config commit.template .gitmessage
Or, you can just create a file .gitmessage and add the commit body suggest above. Next time you make the commit, just type "git commit", and a text editor will apears(in my case, VIM). Fill all the commit body with the data you want to describe.
finally, it is totally possible to change the commit body text
What do you think about this suggest? @wwahammy
There is a example of commit template and commit policie above.
@pedrohelias thanks for the suggestion. I'm not convinced this is really what we want. Consider the following situations:
- a commit addresses an issue but doesn't finish it, just works on it.
- a commit fixes something that was never documented as an issue.
I think forcing people to use this might add additional work that, given the small size of our project, isn't really valuable.
I'm open to other ideas though so feel free to share.
Hi @wwahammy , sorry for the delay. I think I didn't explain it right. I will work in my proposal, make some corrections to cover the examples and be more simple to other contributors. Thanks for the feedback. Still on this week I will be back here.
Hello @wwahammy, on below you will find a version 2.0 of the documentation we proposed, but know, with some changes, to meet those examples that you bring to this issue. Additionally, we made Pull Request policie proposal. I believe this will help you a lot with de manager of the project, in my thoughts, this will help you to understand better the contributor. I adjusted the policies for meet from the simple case to more complex case, and meets all the kinds of contribuiton. There are optional things in this proposal, that you are not forced to follow to contribute with the project, so is possible to go on with simple policies suggested that by itself already helps to organize de project - I paid attention to this to cover your way of thinking about the project. It's important to keep in mind that this sugestion can be altered. Please, consider take a look :)
Commit Policies
Simple Cases
IMPORTANT: This method is recommended for simple commits, simple alterations on the code. With the issue tagged, is possible to know, premeditatedly, if a Issue is still open and live. Most of the work will use this commit format, because of the highly friendly and simple way to do.
Commits are essential for tracking changes and additions to the project.
The imperative mode (assertive actions and orders) should be used to mention what was done.
If the commit concerns a simple issue, make the commit as follows:
git commit -m "#IdIssue - Message"
A more Complex Case
IMPORTANT: Is just necessary to keep in mind to use this method only in the case that the commit it's not about some usual fix, a quickly alteration, or addition of a small snippet of code. This method is for more complex alteration. Do not use in case of a simple commit. Pair programming, per example, can make use of this form better than the simpler form. One more time, if your alterarion is very simple, we encourage you to use the simple way, like was said before - just type "git commit -m "#idIssue - Message" and go on.
Due to its importance, if the commit concerns something more complex, use the following template for standardization, replacing the text of the comments '# will not be read in the commit':
. #Id-of-Issue - Commit title: start with capital letter, objective
# No more than 50 chars, this line has 50 #
#Skip line
# Body: Explain what and why
# No more than 72 characters (this line has) #
#OPTIONAL: If there is, include this line of co-authors of your commit for each contributor.
#Skip 2 lines
# Co-authored-by: name1 <user1@users.noreply.github.com>
# Co-authored-by: name2 <user2@users.noreply.github.com>
#Skip line
To use the template, add the template file .gitmessage, being in your local repository folder, at the root, as follows:
git config commit.template .gitmessage
Or, you can just create a file .gitmessage and add the commit body suggest above. Next time you make the commit, just type "git commit", and a text editor will apears(in my case, VIM). Fill all the commit body with the data you want to describe.
finally, it is totally possible to change the commit body text
Pull Request Policies
To join branches to the main, we have to make a Pull Request (PR), pointing what about the problem (solved or not is), what was done, and what issue(or issues) were resolved. To make a more complete PR, it is suggested the template below:
IMPORTANT: It's recommended use the WIP term in case of the Pull Request is a work-in-progress. This term indicates that: the code has not finished, wants a feedback of the present work until now, or just use the CI infrastructure of the project. To use this, just type [WIP] on a prefix of a Pull Request that you are working on. This trick helps a lot the manager of the project.
# About the description
Include here a little overview of what was changed and the Issue that you worked(are working), with the context. List all dependences that are not concluded for this PR be considered finished. Is very important cite if the issue is closed or not.
Here you can put images too, if this will help you to explain the work.
## The types of changes made
- [ ] Bug fix
- [ ] New Feature
- [ ] Breaking change - means some alterations that can break or change the current system functioning
- [ ] Document alteration
# How was tested
Describe the tests you ran to validate the code.
# Checklist:
- [ ] My code follows the project principles.
- [ ] I revised my code.
- [ ] I commented my codes to help other person who will read it later
- [ ] My contribution does not generates problem or error to run the code.
- [ ] I tested my code to validate the solution.