CONTRIBUTING.org

Introduction

Nice to meet you 😄.

Wherever we end up going from here:

Thank you for spending your precious time and valued brainpower—it is truly appreciated!

This contribution guide exists so that you and other contributors will get the most out of your effort for the least amount of time and expenditure required. It is simple—we are looking for all and everything you view as a contribution.

Areas To Contribute

• Improving documentation.
• Bug triage.
• Writing tutorials.
• Feature ideas.
• “Simple things” like spelling and grammar fixes, typo correction, white space, and formatting changes
• Refactoring.
• Support questions: yes, really! If you are facing it, then you can’t be the only one. It is an opportunity to better the documentation, the package itself, or more. Create a “Blank” issue type to ask your question since it is neither a bug report nor a feature request.
• Whatever things that aren’t listed here that should be.

Contribution Expectations

Documentation

80% of the time, your changes require either an update to the project documentation, the source code documentation, or BOTH. The literal changes your contribution made is crystal clear: the commits explains everything. However, the context for your change, the thought process you followed, and examples of its use are not. There might be little to no documentation required for bug fixes and minor changes: it should be self-evident. For new features, though, assume that you will have to put some real thought into the new documentation. Assume that your fellow bloggers are unfamiliar with the feature area. You are introducing the feature area, the problem you faced using it, and the solution you created for them for the first time. 80% of the time, your fellow users are either using this feature for the first time, or have used it and won’t precisely understand it solves. The saddest software is the one that never runs. Unless you update the documentation, other users will likely never learn about your contribution, and the code will essentially die. Consider it your duty, responsibility, and gift to future users to make your donation accessible in both the code and the documentation. Please take this as an opportunity to have some fun changing how other Org2Bloggers think: you are making the Org2Blog universe a better place and all of the greatly appreciate it.

Coding style and conventions

The Emacs Lisp code should follow the Emacs Lisp conventions and the Emacs Lisp Style Guide. Write easy-to-understand code. That doesn’t mean going overboard, though! It just means write code that humans can follow simply by reading and that you can easily debug with Edebug. For example, instead of writing multiple expressions embedded many levels deep, use a let* to write sequential code: it is easier to understand. Make variable names with full words in all but the most straightforward cases. For example, regular expressions are defined in a two-item list: the first item is the logical name of the regex, for example, “birthday,” and the second item is the actual regex pattern to match. Instead of binding the logical name and regex to n and r instead bind them to rxname and rxpattern~—another example handling function results. Bind the result of the function to a variable before returning it: ~(let ((result (hard-work-here))) result). That way, you can quickly identify where the function logically ends and additionally can set a breakpoint there and play around with eval‘ing code during the function’s execution (use edebug-defun). Sometimes you run into situations where there is no logical way to proceed through a function, and the best solution is to exit the function. You may never have heard of this before, but you /can/quickly write this style of code using catch and throw. Although there is a stigma attached to this sequential code in Lisp, it is essential for writing real-world functions as you do in Org2Blog. An additionally, you can combine that with condition-case-unless-debug for precise error handling. A good example is how to handle errors in functions where you don’t have to leave the function but need to quickly abort what you are doing, notify the users, then decide what to do next. When you write non-trivial functions, as are most, it will help you make sense when you are writing it and make it easier for future maintainers. Overall write code to make it easy for future maintainers to maintain: it will result in more accessible and higher quality code for you to write right now and for all maintainers in the future.

Grammar and Language

Use a spell-checker like Aspell and grammar-checker like LanguageTool for your docstrings and documentation. Find writing problems like weasel-words, passive-voice and duplicate words with Writegood Mode. The best tool available today is Grammarly, and I recommend it above everything else out there. For project documentation, don’t break long lines (for example, using Auto Fill Mode) because tools like Grammarly and LanguageTool work on an unbroken sentence. When you give them separate lines, it sees each one as a new paragraph making the tools unusable. It becomes tedious to read long lines, though: the solution is to use Visual Fill Column to mimic the effects of breaking your lines.

Use quality-checking tools

Use flycheck, package-lint and flycheck-package to help you identify common errors in package metadata and code. Use checkdoc to make sure that your package follows the conventions for documentation strings.

Review existing issues

The issue tracker may already have them solved; otherwise, they are a great place to start

The Future

The future file may already have new features listed, and if it doesn’t, then maybe it should. Either way, it might be a great place to start.

Accept the license

Org2Blog is licensed GPLv3: you understand and submit your code under those terms.

Conclusion

That is it. That would be everything. If you made it this far: kudos to you for sticking around. Thank you for spending your time here. I hope you keep blogging and having fun with Org2Blog.

Thanks and have a great day.