search

picocms / Pico

Pico is a stupidly simple, blazing fast, flat file CMS.
http://picocms.org/
MIT License
3.82k stars 616 forks source link

Pico 1.0 development & release process #268

Closed PhrozenByte closed 8 years ago

PhrozenByte commented 8 years ago

The phpDocumentor folder of the gh-pages branch (introduced with Pico 1.0 resp. #260) should be automatically generated when both a release is published (create a distinct phpDocumentor folder for any minor release - see http://semver.org/) and someone commits to the master branch.

By the way, our ToDo list for the final 1.0.0 release:

Deferred:

theshka commented 8 years ago

What does our build and release pipeline look like? How should this be accomplished automatically?

PhrozenByte commented 8 years ago

Actually I'm not sure about this, I think this can be achieved using one of those third-party tools (in GitHubs terminology "Webhooks, Services and Integrations"). In the past, either someone else did this or I did it manually so I don't have experience with that. I had the impression that maybe @dav-m85 has experience with it? Otherwise someone has to familiarize with this topic...

Manually the process looks more or less like this:

  1. create & push a Git tag
  2. run composer locally
  3. create a ZIP archive from the resulting installation directory (so vendor/ is included)
  4. draft a release on GitHub (including the corresponding parts of the changelog.txt)
  5. upload the ZIP archive as binary
  6. run phpDocumentor locally, output goes to a new folder in the gh-pages branch
  7. link the new phpDocs directory on the website
  8. commit & push the changes to the gh-pages branch
theshka commented 8 years ago

I've added a section to the development documentation for this (https://github.com/PhrozenByte/Pico/pull/5)

If someone could point in the right direction, I could start to familiarize myself with the topic as a contingency. Would something like travis-ci be the tool for the job?

dav-m85 commented 8 years ago

@theshka @PhrozenByte yes, travis is the tool for the task. It has a github release upload feature that allows to run a build for a specific tag and push the corresponding release tarball into github.

It has also a more advanced artifact build feature, but it requires to have a s3 instance somewhere to host the builds.

PhrozenByte commented 8 years ago

@theshka: Following http://semver.org/ looks like a good choice, so instead of releasing 1.0-beta we'll release it as 1.0.0-beta.1. The final version is 1.0.0. Are you through with that?

Regarding branches: I know many projects using a separate develop branch (most of them because they are using Vincent Driessens git-flow concept). In our case I don't think it is necessary to use such a complex workflow. Development should happen in the master branch, we consciously don't tell people to use the master branch, but tags. A regular user downloads the binary anyway, even when using composer we suggest to use the latest tag in our README.md. Assumed we have concurrent versions in the future (I don't think this will happen...) we can simply create a oldstable branch. I suggest to use PRs for everything, so you (and anybody else) can look through my changes before merging and I can look through your changes. As far as I know that's exactly the workflow recommended by GitHub (and I like it because of its simplicity) :smile:

What do you think? @dav-m85 and @all, your feedback is appreciated, too :smiley:

theshka commented 8 years ago

I am not opposed to working in the master branch and continuing to use PR's for everything @PhrozenByte, nor am I opposed to sticking with semver and the resulting 1.0.0-beta.1/ 1.0.0. :+1: I'll keep updating the plugin-dev page as we work out the details for the release process as well.

PhrozenByte commented 8 years ago

Just for clarification: I suggest to use branches within the picocms/Pico repo, not within our own forks. For example, a future pico1.1 branch should be part of the picocms/Pico repo, not of a fork. As soon as development reaches a point where feedback is appreciated, a PR is opened. After some time (very soon for bugfixes, other improvements should have a reasonable feedback phase) the PR is merged and the branch can be deleted.

Anyway, this just affects @picocms, @theshka and me. It makes working together on new features much easier, the current situation of constantly opening PRs on my fork just to merge small changes isn't good. By the way, for the transitional phase (until Pico 1.0 is finally merged) I added you as Collaborator to my fork so you don't have to open PRs all the time.

I suggest to prefix our development branches reasonable, e.g. feature/ for bigger features, enhancement/ for smaller improvements and bugfix/. What do you think?

theshka commented 8 years ago

I like the idea of prefixing branches as you have defined @PhrozenByte , it will obviously help to keep things in order and I don't see any reason to not adopt that change as well. I will add it to the documentation.

dav-m85 commented 8 years ago

From my own experience, this is indeed the best process with a small team like here. Let's create branch pico 1.1 as soon as 1.0 is merged.

Regarding the semver, I'm not sure about going alpha/beta/rc/release. This heavier semver cycle is meant for getting feedback from the community. IMHO, let's release 1.0.0 straight !

PhrozenByte commented 8 years ago

I would like to receive a little more feedback about Pico 1.0 before releasing it as Picos first stable release (especially more testers with a bigger variety of plugins). The PR imho hasn't received enough attention for this massive update yet. Going through the whole alpha/beta/rc/release process is indeed not necessary, a (hopefully single) beta should be sufficient to get the wanted feedback and we can release Pico 1.0 some weeks later. It's probably not necessary do repeat this in the future, but Pico 1.0 is a little special. :smile:

theshka commented 8 years ago

There is a part of me that wants to merge this straight away too @dav-m85 , but I think we should stick with @PhrozenByte's plan to release this as Pico 1.0.0-beta.1, then scrap the extended a/b/rc/r release process for subsequent releases of Pico.

That said, I don't know how much more feedback we can reasonably expect. I think many people have moved on from Pico entirely, and the #252 thread has already seen the most participants in a conversation for some time. What are you thinking as a timeline @PhrozenByte?

Additionally, do we have an idea of what we still need to accomplish before moving ahead? I'd like to help anyway I can, sometimes it's just not clear where to jump in :laughing:

PhrozenByte commented 8 years ago

Actually just the website updates are missing, concretely a little more dev docs and the missing sections of the user docs. Unfortunately my time is limited at the moment :(

I really hope releasing Pico 1.0.0-beta.1 gives us the wanted feedback. Many users don't want to follow dev talks, but will test a new release. Releasing it as 1.0.0 straigth bears the danger of problems and disenchanted users. Imho Pico 1.0 simply wasn't tested enough yet...

Regarding phpDocumentor: According to travis-ci/travis-ci#2111 and some own testing, it isn't possible to combine branch whitelists with tag-based auto deployment. Unfortunately it is necessary to whitelist the gh-pages branch, because Travis implicitly blacklists it. As far as I can tell we have two options: Either wait for travis-ci/travis-ci#2111 to be resolved and creating the class docs manually until then (the issue is from March 2014, so I don't have the hope that this will happen soon :disappointed:) or let @picocms create a distinct picocms.github.io repo. :unamused:

PhrozenByte commented 8 years ago

I suggest to delay the dev docs after the release of Pico 1.0.0-beta.1. We should finish the dev docs before releasing Pico 1.0.0, but I think we shouldn't delay the beta release much longer... I'll finish the user docs within the next days, so I suggest to merge #252 and #260 on Friday, 6th November. What do you think?

theshka commented 8 years ago

That's agreeable @PhrozenByte, I updated the due date on the Version 1.0.0-beta.1 milestone, and created another for the full 1.0.0 release. :+1:

PhrozenByte commented 8 years ago

Jekyll and especially its template engine Liquid drove me nuts... :unamused:

Apart from the missing "Ensure restricted access" section on the upgrade page (I'll add just a few sentences tomorrow) the website and Pico 1.0 is ready to merge. As you probably already noticed I made some last-minute changes to Pico 1.0 that arose while I wrote the docs. Hence I would say we shouldn't stick very strict on "don't add new features" between 1.0.0-beta.1 and 1.0.0... Maybe there are some more things we forgot to address.

I'll merge both PRs tomorrow towards evening ("evening" in terms of UTC).

Any wishes, problems, complaints or comments? :smiley:

theshka commented 8 years ago

Looks like things are starting to come together :+1:

As you've said before, this is a special version of Pico, being flexible with the newly introduced SemVer requirements when going from beta.1 to 1.0.0 is totally reasonable.

I briefly went over the upgrade.md page to correct spelling/grammar, then thought: when upgrading content files from 0.x to 1.0.0-beta.1 does one need to change the .md file headers from /*...*/ to --- ... --- to reflect the changes made by introducing YAML? This should be mentioned somewhere in the upgrade page as well.

PhrozenByte commented 8 years ago

No, it's not necessary to change the .md file headers from C-style comments to the YAML Front Matter syntax. Admittedly Pico::parseFileMeta() says that C-style comments are deprecated, but I don't think it will ever be necessary to drop the support of them. Anyway thanks for this hint, I'll add a sentence about it, the page also doesn't mention that meta headers must start on the first line of the file now.

PhrozenByte commented 8 years ago

@theshka: I pushed the missing additions, can you please look through them so I can merge the PRs?

theshka commented 8 years ago

@PhrozenByte, I reviewed the changes. Looks good :+1:

PhrozenByte commented 8 years ago

Here we go :smiley:

Unfortunately the auto-generated release didn't work as expected. It indeed took the tagged commit to give the release a title and message, but the the title was v1.0.0-beta.1: Version 1.0.0-beta.1 (i.e. the tag name was prepended) and the message wasn't parsed with Markdown. I had to copy the contents over manually.

http://picocms.org/ requires a forced Refresh to work (Strg + F5).

PhrozenByte commented 8 years ago

I tried to clarify the suggested branching concept in 6638c2b, @theshka, do you agree with that?

How do we want to proceed regarding the automated generation of phpDocs?

edit: @theshka moved the to-do list to the top of this post, so that it shows up in issues overview

theshka commented 8 years ago

Yeah, the branching concept makes good sense @PhrozenByte, I was on a little hiatus, but will start knocking off some of this ToDo list this week. :)

mayamcdougall commented 8 years ago

@PhrozenByte I could probably make up a "What's New" section sometime tomorrow. Since it's in the Upgrade section, I assume it should be a pared down version of the change log. Something of a user-friendly "What do I need to know to upgrade" list? I was thinking of breaking it down into two sections, one "for users" and one "for developers". And maybe include a link to the change log for additional details.

I could also work on getting some of those cookbook ideas into a full page of developer tips (and/or merge them into applicable areas of _docs).

PhrozenByte commented 8 years ago

Actually the "What's New" section should be a more extensive (and not pared-down) version of the changelog. It should describe the changes in a not so "techy" manner (i.e. addressing users, so the description of changes only affecting devs can be shorter). From CHANGELOG.md:

This changelog only provides basic information about the enormous changes introduced with Pico 1.0.0-beta.1. Please refer to the UGPRADE section of the docs for details.

With "UPGRADE section of the docs" we ultimately mean the upgrade.md (what is linked by _docs/upgrade.md). The upgrade.md already contains a first (currently commented out) version of the "What's New" section, its sufficient to overhaul and extend these contents. @theshka wrote them on basis of my pull request message.

Splitting the section into a "for users" and a "for developers" part seems to be a good idea, nevertheless the "real" upgrade steps for developers (i.e. "How to upgrade my plugin" - the equivalent to the first paragraphs of the "How to upgrade" section in the upgrade.md) should go to _plugin-dev/upgrade.md. This section should basically be a more extensive version of this comment.

A "How to upgrade my theme" section shouldn't be necessary, the changes are already described in the existing "How to upgrade" section in the upgrade.md. I think most users are using custom themes, so these steps also affect ordinary users and thus shouldn't be part of the dev docs. I think you know the necessary steps pretty well, so you can verify this and make additions/changes when necessary :smile:

The cookbook should stay independent, as its concept is to provide a collection of various code examples. Every example should have a "The problem" and "The solution" part describing the example step-by-step. The "Blogging" section of the docs should be part of the cookbook instead, not of the user docs. The cookbook should finally be mentioned both in the user and dev docs.

mayamcdougall commented 8 years ago

I guess when I said "pared down", I meant in regards to the separating out the developer stuff. Make the user-facing changes clear and well explained, while downplaying the backend fixes that a user doesn't need to worry about.

What's New?

For Users

config.php has moved to config/config.php and new options have been added. Be sure to move your existing config and update it if needed.

You can now define Custom Meta Headers for use in your themes. Access custom headers using {{ meta.yourheader }} in your template or %meta.yourheader% in your content files

For Developers

  • Inaccessible files are now excluded from pages list
  • Pico now requires PHP >= 5.3.6

It sounds like we're on the same page, you just explained it better. Also, after writing this comment, I realized that I've been looking at the wrong upgrade.md (the presumably live version in _docs). The current version does look pretty good. It's thorough, if a bit dry to read. I feel like a "For Users" section should be one part "easy to read" and one part "TL;DR".

And the cookbook thing I was thinking of merging with docs was the "assets" page you already took care of. :unamused: I do like the idea of a "the problem/the solution" format though.

PhrozenByte commented 8 years ago

Exactly, the _docs/upgrade.md states just some "generic" steps to upgrade Pico, the actual upgrade tutorial for Pico 0.8 or 0.9 to Pico 1.0 can be found in the upgrade.md. The current "How to upgrade" section already describes some changes relevant for users, consequently the new "What's new" section should indeed give a hint about them, but shouln't repeat them. The main part of the "How to upgrade" section (without its sub-sections) already is a kind of "tl;dr", I'm not sure how we could make this shorter. Anyway, I look forward to your pull request, thank you for helping us! :smiley:

mayamcdougall commented 8 years ago

I'm trying to rework the entire upgrade.md right now. The commented area is much easier to read, so I'm working it into the rest of the document and rewriting it where needed. The main issue I see is that there is a lot of information all over the place. Much of it seems redundant and is clearer in some areas than others. I'm going to make it "flow" the best I can.

Also, is the intention that this will replace the _docs/upgrade.md section of the site, or should it be a separate page? Right now it feels like it's written as a separate page. At the very least it seems like it should be it's own, independent section (probably below the generic upgrade section) because the changes from 0.9 are likely much greater than any changes going forward (the handling for which are already covered in the generic section).

PhrozenByte commented 8 years ago

No, it's intended to keep _docs/upgrade.md (i.e. the user docs) and the upgrade.md (distinct page about upgrading to Pico 1.0) separated (i.e. a completely separated page - as it is right now) - the first describes the upgrade process in a generic manner without saying a single word about the changes, the latter is just about upgrading to Pico 1.0. Actually I don't think that it's necessary to change _docs/upgrade.md at all.

Please keep in mind that the "What's new" section should extend the "How to upgrade" section, not the other way round or that a user is required to read both sections. It should be obligatory for a user who's upgrading to Pico 1.0 to read the "How to upgrade" section, reading the "What's new" section should be completely optional. Therefore the "How to upgrade" section should describe only features that could possibly affect backwards compatibility (now or in the future), whereas the "What's new" section describes all (better: not yet mentioned) user-relevant changes.

mayamcdougall commented 8 years ago

Good, because what I've got so far sounds like just what you're looking for. It's still a work in progress, but I've restructured a lot of it. I'll submit a pull request in a few min so you can check out the direction I'm going in.

theshka commented 8 years ago

Added README.md to gh-pages branch in 66bcb181cc82d760573a00d2bf472e4c7fb900c9

theshka commented 8 years ago

@PhrozenByte: Decide where to put links to it (inline user docs? website user docs? website dev docs?) and actually create the links

I think the link to cookbook would be good in the Getting Help ... for users part of the docs. It's likely they are the ones who will benefit most. I also added a blurb about it to the Wiki.

PhrozenByte commented 8 years ago

I suggest to fit a 1.0.0-beta.2 release in, what do you think?

theshka commented 8 years ago

Considering there have been numerous large changes between 1.0.0-beta.1 and now, I wouldn't oppose another beta cycle.

I know it would be a pain at this point, but I was thinking, how would you feel about moving all Pico user/source files in a src directory; isolating the build-related directory and files in the root of the project? Do you think this would unnecessarily complicate things, or provide better cohesion and organization when viewing the project files?

PhrozenByte commented 8 years ago

Hmm... Makes it harder for composer users to set up their website.

theshka commented 8 years ago

Alternatively, can we hide/prefix the files .phpcs.xml, .index.php.dist,_build?

PhrozenByte commented 8 years ago

Yeah, renaming phpcs.xml to .phpcs.xml and build to _build sounds reasonable, the index.php.dist should remain unchanged - as a hint for composer users to use this file when possible.

theshka commented 8 years ago

Made the changes in #295, whenever you get a free minute, just make sure I didn't miss any :)

theshka commented 8 years ago

Sorry @PhrozenByte, just to clarify... should we clear up the 4 remaining PR's and 4 "To-Do" items in this thread before tagging v1.0.0-beta.2 and starting the second beta cycle?

PhrozenByte commented 8 years ago

I'll merge #273 before tagging v1.0.0-beta.2, can you please look through the changes again? All other PR's aren't finished yet, I had no time to look through #276 and we have a ongoing discussion about #292, so we should postpone them.

theshka commented 8 years ago

273 looks good, I like the improved error handling and the update to the inline docs is great :+1:

... I also renamed the milestone and moved the discussed issues to the next version.

PhrozenByte commented 8 years ago

Here we go: https://github.com/picocms/Pico/releases/tag/v1.0.0-beta.2

theshka commented 8 years ago

Nice! :+1: https://twitter.com/gitpicocms/status/671388691143766017

Auto docs is awesome :heart_eyes: https://travis-ci.org/picocms/Pico/jobs/93989737 http://picocms.org/phpDoc/v1.0.0-beta.2

Also, #289 :pray: pico-release-v1.0.0-beta.1.tar.gz = 8.4MB pico-release-v1.0.0-beta.2.tar.gz = 342kb!!!

PhrozenByte commented 8 years ago

:smiley:

Just fyi: The reason why I suggested this intermediate release is, that my time for Pico will be very limited in December and January. So please don't be surprised if my contributions peak off in the next two months.

Lomanic commented 8 years ago

Awesome work :+1: It only gets better and better :smiley: The twitter bot is a nice addition, who owns it?

theshka commented 8 years ago

@PhrozenByte deserves most all of the praise :bow: You've definitely earned that time off in Dec/Jan :laughing:

I'm behind the Twitter account thus far, more of a manual-bot at the moment @Lomanic lol

PhrozenByte commented 8 years ago

Thank you! The progress we made together recently would not have been possible without the kind support by all of you guys, whether by code contributions, writing on the docs or by giving your opinions, ideas or support in general :smiley: Pico got an community project as its best :smiley:

PhrozenByte commented 8 years ago

I would like to suggest the release of the final 1.0.0 within the next days (on Thursday would be perfect, kind of a Christmas present :smile:). I also suggest to defer the overhaul of the "Development" and "Cookbook" pages on our website - they are nice to have, but not absolutely necessary, especially because we actually don't loose any information compared to Pico 0.X. I merged all remaining pull requests yesterday and will look through the outstanding parts of the upgrade.md (#276) today (edit: done). Please take a look at #306 and the commits (especially a853925abc1e5e9263a7aba3f95ce2a9f37f5c0a and 4751bcf6eef45c98c0e59109bfcae49b7e3e5816) I pushed recently.

As elucidated in https://github.com/picocms/Pico/pull/297#issuecomment-161146348, I'm planning to release Pico 1.1 pretty soon (by way of comparison: #252 is 4 months old, v1.0.0-beta.1 1.5 months) - probably within the first quarter of 2016. @theshka, what's about https://github.com/picocms/Pico/pull/297#issuecomment-164336279?

What do you think? (especially, but not exclusively, @theshka)

mayamcdougall commented 8 years ago

As far as the docs/website changes go, I don't see a reason to think of them as being "tied" to this release. Sometime I plan to go through it all and work out any rough or hard-to-read sections. Other than the upgrade page(s) though, nothing else needs to be tied to the 1.0.0 release, so why not keep things "rolling" and silently update each section as the work gets done?

I definitely like the changes in #306, and would even like to see something similar implemented in the default Pico theme (perhaps for 1.1). It's just a little too simple as is, and I think it gives the wrong impression of how powerful Pico can be. I wouldn't mind putting some work into this idea in the future, since it's one of the few things within my coding capabilities. :smiley:

I'd also be willing to work on writing some paragraphs to go with those cookbook examples (and future ones) that way it can grow into a proper page instead of a bunch of unexplained code. Right now we have the ingredients of the cookbook, but it still needs some cooking steps.

I look forward to the final release of 1.0.0. As @theshka said almost a month ago, @PhrozenByte you've done so much work to revive/reinvigorate Pico and bring about this release. I think a quick look at Contributors says all that needs to be said about the time you've put into this project. Thanks for all your hard work. :tada: :+1:

PhrozenByte commented 8 years ago

Yes, a completely refactored default theme is one of the key features planned for Pico 1.1, please refer to #270 for details. I'm even planning to use Pico for our website, but that's probably something for the more distant future than for Pico 1.1. Your help is, as always, very appreciated! :smiley:

theshka commented 8 years ago

I've modified the due date on Version 1.0.0 Milestone, Merry Ho-Ho :santa:

:+1: