Want to contribute ?
GitHub + MELPA + Worg is one popular way to publish your contribution.
I wrote this tutorial because I went this path and it was not so obvious before starting.
(You may also want to look at How to Contribute to Org for a tighter integration of your contribution with Org-mode)
1. So what are those beasts ?
This is a repository of Emacs packages contributed by many people. To get a taste of it, do that:
- Add those lines to your
(require 'package) (add-to-list 'package-archives '("melpa" . "http://melpa.milkbox.net/packages/") t)
- Execute those lines by typing
C-x C-eat the end of both lines.
After a few seconds you should get a never-ending list of packages, right available for you to use. Just click on one and hit the "install" button.
There are several ELPA repositories, MELPA being a popular at the time of writing.
It is a code repository, open to all. Browse it here: https://github.com
It is based on
GIT, wihch is a "version control system".
There are many version control systems: CVS, SVN, Bazaar, to name a few.
On GitHub, you manage your own GIT repositories.
It is a collaborative website for everything about Emacs Org-mode. GIT is used as its versionning backend. You may request commit-rights on it, as explained here: https://orgmode.org/worg/worg-about.html
2. General workflow
- Create your Emacs package,
- Register to GitHub (it is free),
- Put your package under version control on GitHub,
- Make it compliant with ELPA,
- Submit your package to MELPA through a "pull request",
M-x package-list-packagesand try installing your own package,
- Ask for commit rights on Worg,
- Document your package on Worg,
- Announce its availability on the mailing list,
- Your package starts its life with possible contributions from others.
You may change the ordering of items. For instance, putting 9. on position 1. is done quite often, and it could save you a few iterations.
3. Creating your package
Well, you know, you write a bunch of Emacs-lisp files, and possibly
other kinds of files. I will take my own example: I wrote
4. Registering to GitHub
Under a single account, you can create as many GIT repositories as you want.
Go ahead, create one using the drop down menu under the "+" sign at the upper right side of the screen. Play a little bit. No worries, you can delete it.
5. Put your package under version control
There are many ways to do that. My advice is to let GitHub create a skeletton.
- Create a repository (drop down menu under the "+" sign at the upper right side of the screen).
- Choose the GPL V3 license for your package (or any other license). GitHub creates the license file for you.
Clone the repository to your local drive. In my case I did that:
git clone https://github.com/tbanel/orgtblasciiplot.git
This will create a directory with the name of your repository, ready to accept GIT commands. You will mainly develop in this local directory.
Copy the files of your package in this directory. For me it was something like:
cp orgtbl-ascii-plot.el orgtblasciiplot/
Add your files to GIT. I typed:
git add orgtbl-ascii-plot.el git commit
Synchronize your local drive with GitHub servers.
This will "push" changes in your local drive to GitHub.
- On the GitHub web interface, click on
Editbutton. Explain what your package do. Play with the markup facility, use the
Previewbutton. When done, commit.
Now you have two repositories, one on your local drive, and one on GitHub. You may change either, as you want, maintaining both in sync with the commands:
git push git pull
6. Make your package compliant with ELPA
You need to tag your elisp file in a way that ELPA can leverage automatically.
A simple way to do that is to create an empty
under Emacs (replace with the actual name of your package).
auto-insert-mode is enabled, a template is inserted.
Then go to the Emacs info page for details: elisp#Packaging
7. Submit your package to MELPA through a "pull request"
Submissions to MELPA work this way:
- Fork the MELPA project under GitHub.
Login to your GitHub account,
go to https://github.com/milkypostman/melpa,
click on the
Forkbutton. This will add a "copy" of the MELPA repository into your account. This copy is yours, you can do whaterver you want with it, it does not interfer with the original one.
Clone it to your local drive.
git clone https://github.com/tbanel/melpa
(do not forget to change tbanel to your actual GitHub account)
Change it as explained in the
README.mdof https://github.com/milkypostman/melpa under the "Contributing New Recipes" section. Basically, this involves writting a new file:
(change the name of the file according to the name of your package). Mine looks like this:
(orgtbl-ascii-plot :fetcher github :repo "tbanel/orgtblasciiplot")
cd melpa git add recipes/orgtbl-ascii-plot git commit
Check that your package builds and installs properly
make recipes/orgtbl-ascii-plot emacs & M-x package-install-file recipes/orgtbl-ascii-plot
Be sure to read detailed instruction in https://github.com/milkypostman/melpa, section "Testing"
Send a "pull request" to the MELPA maintainer team. Eventually they will pull your changes out of your copy of melpa.
- Go to https://github.com/tbanel/melpa (change path to your fork of Melpa),
- click on "Pull Request"
- click on "New pull request"
- fill in the comment section with relevant information. For me this was:
_ I would like to submit orgtbl-ascii-plot package to Melpa. > orgtbl-ascii-plot adds plotting capabilities to Org-mode tables, all in Emacs without external dependencies. > full documentation here: https://orgmode.org/worg/org-contrib/orgtbl-ascii-plot.html > GitHub home here: https://github.com/tbanel/orgtblasciiplot > I am the author and maintainer.
This is my first contribution to Melpa. I may miss something, so please tell me, I will fix it.
- Answer queries from the MELPA team. They are very friendly. They do a good job at ensuring that your package is fully compliant with the ELPA process. They may also check additional details, like possible redundancy with another package, or simpler lisp style.
8. Install your own package !
A few hours after your "pull request" has been accepted, il will show up in the list of packages. Under Emacs type:
Install your own package. Wooow !
9. Register to Worg
https://orgmode.org/worg is the community web site for documentation.
The site is maintained under… GIT.
The site is authored using… Emacs + Org-mode.
An org-mode page committed to the Worg GIT repository gets translated into Html, and is visible a few seconds latter.
Ask for commit-right on Worg. Instructions are here: https://orgmode.org/worg/worg-about.html
This involves creating an SSH key, and cloning the GIT repository.
10. Document your package on Worg
Create a file to document your package. I wrote this one:
which is translated on the web site here: https://orgmode.org/worg/org-contrib/orgtbl-ascii-plot.html
Commit and push it. I did that:
git add org-contrib/orgtbl-ascii-plot.org git commit git push
11. Announce availability of your package
There is a mailing list dedicated to Org-mode. Look here: https://orgmode.org/worg/org-mailing-list.html https://lists.gnu.org/mailman/listinfo/emacs-orgmode
Use it to announce your package. You will receive good feedbacks. It is even advisable to announce it before going all the path down to the publication.