We can upgrade the readability of the codes in our repo’s by making some subtle yet important changes,
Goals
Improve efficiency of the workflow by making the codes more readable.
Help new contributors get started.
Give an idea about what features/software’s used in each repo’s or (files/folders) .
We can supply information to a different developer etc.**
Approach
1.Specifying features or software’s used in files ex: add in readme, mustache JS is used for these files.
2.Sometimes people directly code in document.ready rather we can make meaningful function name and use that to code.
Comment on blocks of template (not lines) to specify the functions (only when necessary)
Use explanations of intent or clarification of code( in cases where the goals of the cord are not clear)
Use a warning of consequence (when changes in that cord will effect in several places)
Reward
New contributors will find it easy to make changes rather than struggling to find where to make the specific change.
Knowledge sharing process would happen more rapidly without needing the code owner to explain.
Time consuming and workload can be decreased drastically in the long term run .
Thought to make these suggestions since I was personally struggling in the last issue i was working on with where to make changes. And found out several contributors before me also faced the same issues in contributing.
Please make sure to give your ideas and add more into the approach section and rewards section to make it more productive.
Yes I’ve talked with @anjisvj and @jaye as well , also we can even make several new issues regarding this and add the tag “good first issue” for people to work on them so on top of the readability even the people who will be working on these issues will gain knowledge regarding the features used in the repo’s. @YohanAvishke .
We can seperate a section in the README.md for pull requests. It gives a guide in best practices but not a step by step guide for a pull request. we can add some procedures to follow in sending PRs and also a guide to fill out the prebuilt PR session in the sef-site repo as @Gravewalker described in the knowledge share session.
(A) Shall we drag the Commits/Pull Requests session in the CONTRIBUTING.md to README.md?
(B) Make a separate simplified pull request session to give a brief intro and link the CONTRIBUTING.md Commits/Pull Requests session for further details?
Which option is better . or is there anything better option than both of the above?
