Proper package development workflow with Git and /vendors directory?

[Jake Wilson]

I'm trying to figure out what the proper workflow is for development of Composer packages. Whenever I search for this topic on Google, all the results are how to make a composer.json and/or how to submit to Packagist, etc... I can't find anything that actually talks about the proper workflow of development and changes to your package.

Lets say I have a simple PHP Class I have developed. I give it a composer.json, make it a package, and now I have it on Packagist. Now, lets say I'm ready to start making changes to my package. I have bugs to fix or features to add or something. What do I do?

Do I create an empty test/development project, composer install my package from Packagist, and then start editing my class in the /vendors folder? Now I would have all my changes in the vendors folder, but that isn't a git repository, so how do I commit my changes and push back up to my GitHub repo?

I have read some people suggesting that after doing a composer install of your package, you delete your package directory from vendors and then git clone your GitHub repo into the /vendors folder. So that way your package autoloads into your test/development project but you can still commit and push your changes.

Also, how do you deal with tests? If I'm using phpunit for example, I have a /tests folder for my project. After doing a composer install to bring in my package, do I navigate into vendors/some/path/myclass/tests and run the phpunit command line there? If so, I'm pretty sure my class is not going to be autoloaded into my test suite.

Can anyone point me to some resources of examples or tutorials for what a proper, sound workflow is for Package development?

[Jason Judge]

Hi Jake,

I don't know about "proper workflow!", but here is what I do.

Firstly, I don't mess with the vendor directory. I treat that as the place for installing packages into. I make that a strict rule. So that leaves one real option: make changes to the package outside of the vendor directory.

This is actually pretty simple. In your project's composer.json, you will likely have a require section with a line for your package. That can remain. What we will do, is override what is loaded.

In your composer.json, create an autoload section, then a psr-0 or psr-4 section to point to where your development version of your package is. This is a for project I'm working on now, where I am developing two packages along with the application. :

    "autoload": {
        "psr-0": {
            "Academe\\SugarPortal": "../../dev/sugarportal/src/"
        },
        "psr-4": {
            "Academe\\OpenErpApi\\": "../../openerp/academe-openerpapi/src/"
        }
    },

The autoload for those two packages points to where a branch of those packages have been cloned for working on.

I must remember to remove those autoload sections before pushing the application to production. There will be other workflows that could be used, all with pros and cons, and it largely depends on how self-contained the development of your packages can be. With my example here, the packages and application are being developed together, but I still want to end up with a portable package that I can use on other projects, rather than have it all in the core of the application.

Hope that helps, and gives you one possible way forward.

-- Jason

[Jason Judge]

Don't forget to tell composer about the new autoload section once you've added it:

php composer.phar dump-autoload

[Jake Wilson]

Okay that is helpful. Let me get this straight: In my dev project composer.json, do I require my package just like normal? Or only specify the autoload path? Because if I don't require my package, and my package depends on other packages, those other dependencies won't be pulled in. Is that right?

[Jason Judge]

On Tuesday, 9 September 2014 20:36:19 UTC+1, Jake Wilson wrote:

Okay that is helpful. Let me get this straight: In my dev project composer.json, do I require my package just like normal? Or only specify the autoload path? Because if I don't require my package, and my package depends on other packages, those other dependencies won't be pulled in. Is that right?

Yes, you are right - do both. The autoload appears to override the autoloading of a required module (not sure if by design, or has just worked this way for me on shear luck), so you can pull in the dependencies and the package as currently released or from a tag in a repository, but at run-time the autoloading will search a clone outside of the vendor directory, where-ever you point the autoloading at.

-- Jason

[Jake Wilson]

Okay, this is working perfectly. Really a brilliant solution. I really don't understand why it was so hard for me to find someone to explain this idea to me. I've never found any articles, documentation or tutorials that suggested this approach. It really is the perfect way to do it. It's great because you composer install your project to a dev environment (which also pulls in any package dependencies) but then your class is autoloaded from your local repo that exists in some other directory. Perfect. Thank you!

Jake

[Tim Otten]

On Tuesday, September 9, 2014 5:39:00 AM UTC-4, Jason Judge wrote:

On Monday, 8 September 2014 22:45:51 UTC+1, Jake Wilson wrote:

Can anyone point me to some resources of examples or tutorials for what a proper, sound workflow is for Package development?

I don't know about "proper workflow!", but here is what I do.

...

I must remember to remove those autoload sections before pushing the application to production. There will be other workflows that could be used, all with pros and cons, and it largely depends on how self-contained the development of your packages can be. With my example here, the packages and application are being developed together, but I still want to end up with a portable package that I can use on other projects, rather than have it all in the core of the application.

In the interests of exploring those different workflows and their trade-offs, here's a bit about my workflow: I generally use composer to setup git repos inside the "vendor" tree and often do development within that tree. The workflow involves a few key commands:

  + "cd myapp ; composer install --prefer-source" -- This tells composer to use git/svn instead of tarballs.
  + "cd myapp/vendor/foo/bar ; hub fork" -- This creates a fork of the project in my Github account ( https://github.com/github/hub )
  + "cd myapp ; git scan st" -- This scans the directory for git repos and summarizes the statuses ( https://civicrm.org/blogs/totten/developer-tip-managing-multiple-git-repositories )

Some considerations:

  + For day-to-day work, there's no need to munge composer.json.
  + However, I do run "git scan st" regularly to make sure that everything is in order.
  + If using an IDE, configuration is simple -- just open the main project root. (No need to import multiple directories.)
  + I think of composer.json as a social document -- i.e. something which affects collaborators and our relationships.
  + Possible bias: In my work, I deal with several projects which have a weak history of developing standalone "libraries" -- they still heavily rely on "plugin" architecture (where you have an app like "Drupal" or "Joomla" combined with bunch of optional plugins). I suspect that this produces different attitudes/workflows/issues (but don't have any deep comments or explanations on how/why).

[Николай Колесниченко]

I think, that using --prefer-source is best practice, becouse composer docs tells us:

• --prefer-source: There are two ways of downloading a package: source and dist. For stable versions Composer will use the dist by default. The source is a version control repository. If --prefer-source is enabled, Composer will install from source if there is one. This is useful if you want to make a bugfix to a project and get a local git clone of the dependency directly.

So, I think, it's the  proper workflow.

Another thing, to use git subsplit for subsplit some parts of application to reusable read-only repo.