Pico 1.0 development & release process #268
Comments
|
What does our build and release pipeline look like? How should this be accomplished automatically? |
|
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:
|
|
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? |
|
@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. |
|
@theshka: Following http://semver.org/ looks like a good choice, so instead of releasing Regarding branches: I know many projects using a separate What do you think? @dav-m85 and @ALL, your feedback is appreciated, too 😃 |
PhrozenByte
changed the title
PhrozenByte
changed the title
|
I am not opposed to working in the |
|
Just for clarification: I suggest to use branches within the picocms/Pico repo, not within our own forks. For example, a future 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. |
|
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. |
|
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 ! |
|
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. 😄 |
|
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 😆 |
|
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 |
|
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? |
|
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. 👍 |
|
Jekyll and especially its template engine Liquid drove me nuts... 😒 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 I'll merge both PRs tomorrow towards evening ("evening" in terms of UTC). Any wishes, problems, complaints or comments? 😃 |
|
Looks like things are starting to come together 👍 As you've said before, this is a special version of Pico, being flexible with the newly introduced SemVer requirements when going from I briefly went over the |
|
No, it's not necessary to change the |
|
@theshka: I pushed the missing additions, can you please look through them so I can merge the PRs? |
|
@PhrozenByte, I reviewed the changes. Looks good 👍 |
**Note:** 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.
```
* [Security] (9e2604a) Prevent content_dir breakouts using malicious URLs
* [New] Pico is on its way to its first stable release!
* [New] Provide pre-bundled releases
* [New] Heavily expanded documentation (inline code docs, user docs, dev docs)
* [New] New routing system using the QUERY_STRING method; Pico now works
out-of-the-box with any webserver and without URL rewriting; use
`%base_url%?sub/page` in markdown files and `{{ "sub/page"|link }}`
in Twig templates to declare internal links
* [New] Brand new plugin system with dependencies (see `PicoPluginInterface`
and `AbstractPicoPlugin`); if you're plugin dev, you really should
take a look at the UPGRADE section of the docs!
* [New] Introducing the `PicoDeprecated` plugin to maintain full backward
compatibility with Pico 0.9 and Pico 0.8
* [New] Support YAML-style meta header comments (`---`)
* [New] Various new placeholders to use in content files (e.g. `%site_title%`)
* [New] Provide access to all meta headers in content files (`%meta.*%`)
* [New] Provide access to meta headers in `$page` arrays (`$page['meta']`)
* [New] The file extension of content files is now configurable
* [New] Add `Pico::setConfig()` method to predefine config variables
* [New] Supporting per-directory `404.md` files
* [New] #103: Providing access to `sub.md` even when the `sub` directory
exists, provided that there is no `sub/index.md`
* [New] #249: Support the `.twig` file extension for templates
* [New] #268, 269: Now using Travis CI; performing basic code tests and
implementing an automatic release process
* [Changed] Complete code refactoring
* [Changed] Source code now follows PSR code styling
* [Changed] Replacing constants (e.g. `ROOT_DIR`) with constructor parameters
* [Changed] Paths (e.g. `content_dir`) are now relative to Pico's root dir
* [Changed] Adding `Pico::run()` method that performs Pico's processing and
returns the rendered contents
* [Changed] Renaming all plugin events; adding some new events
* [Changed] `Pico_Plugin` is now the fully documented `DummyPlugin`
* [Changed] Meta data must start on the first line of the file now
* [Changed] Dropping the need to register meta headers for the convenience of
users and pure (!) theme devs; plugin devs are still REQUIRED to
register their meta headers during `onMetaHeaders`
* [Changed] Exclude inaccessible files from pages list
* [Changed] With alphabetical order, index files (e.g. `sub/index.md`) are
now always placed before their sub pages (e.g. `sub/foo.md`)
* [Changed] Pico requires PHP >= 5.3.6 (due to `erusev/parsedown-extra`)
* [Changed] Pico now implicitly uses a existing `content` directory without
the need to configure this in the `config/config.php` explicitly
* [Changed] Composer: Require a v0.7 release of `erusev/parsedown-extra`
* [Changed] #93, #158: Pico doesn't parse all content files anymore; moved to
`PicoParsePagesContent` plugin, but still impacts performance;
Note: This means `$page['content']` isn't available anymore, but
usually the new `$page['raw_content']` is suitable as replacement.
* [Changed] #116: Parse meta headers using the Symfony YAML component
* [Changed] #244: Replace opendir() with scandir()
* [Changed] #246: Move `config.php` to `config/` directory
* [Changed] #253: Assume HTTPS if page is requested through port 443
* [Changed] A vast number of small improvements and changes...
* [Fixed] Sorting by date now uses timestamps and works as expected
* [Fixed] Fixing `$currentPage`, `$nextPage` and `$previousPage`
* [Fixed] #99: Support content filenames with spaces
* [Fixed] #140, #241: Use file paths as page identifiers rather than titles
* [Fixed] #248: Always set a timezone; adding `$config['timezone']` option
* [Fixed] A vast number of small bugs...
* [Removed] Removing the default Twig cache dir
* [Removed] Removing various empty `index.html` files
* [Removed] Moving Pico's excerpt feature to `PicoExcerpt` plugin
```
**Note:** 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.
```
* [Security] (9e2604a) Prevent content_dir breakouts using malicious URLs
* [New] Pico is on its way to its first stable release!
* [New] Provide pre-bundled releases
* [New] Heavily expanded documentation (inline code docs, user docs, dev docs)
* [New] New routing system using the QUERY_STRING method; Pico now works
out-of-the-box with any webserver and without URL rewriting; use
`%base_url%?sub/page` in markdown files and `{{ "sub/page"|link }}`
in Twig templates to declare internal links
* [New] Brand new plugin system with dependencies (see `PicoPluginInterface`
and `AbstractPicoPlugin`); if you're plugin dev, you really should
take a look at the UPGRADE section of the docs!
* [New] Introducing the `PicoDeprecated` plugin to maintain full backward
compatibility with Pico 0.9 and Pico 0.8
* [New] Support YAML-style meta header comments (`---`)
* [New] Various new placeholders to use in content files (e.g. `%site_title%`)
* [New] Provide access to all meta headers in content files (`%meta.*%`)
* [New] Provide access to meta headers in `$page` arrays (`$page['meta']`)
* [New] The file extension of content files is now configurable
* [New] Add `Pico::setConfig()` method to predefine config variables
* [New] Supporting per-directory `404.md` files
* [New] #103: Providing access to `sub.md` even when the `sub` directory
exists, provided that there is no `sub/index.md`
* [New] #249: Support the `.twig` file extension for templates
* [New] #268, 269: Now using Travis CI; performing basic code tests and
implementing an automatic release process
* [Changed] Complete code refactoring
* [Changed] Source code now follows PSR code styling
* [Changed] Replacing constants (e.g. `ROOT_DIR`) with constructor parameters
* [Changed] Paths (e.g. `content_dir`) are now relative to Pico's root dir
* [Changed] Adding `Pico::run()` method that performs Pico's processing and
returns the rendered contents
* [Changed] Renaming all plugin events; adding some new events
* [Changed] `Pico_Plugin` is now the fully documented `DummyPlugin`
* [Changed] Meta data must start on the first line of the file now
* [Changed] Dropping the need to register meta headers for the convenience of
users and pure (!) theme devs; plugin devs are still REQUIRED to
register their meta headers during `onMetaHeaders`
* [Changed] Exclude inaccessible files from pages list
* [Changed] With alphabetical order, index files (e.g. `sub/index.md`) are
now always placed before their sub pages (e.g. `sub/foo.md`)
* [Changed] Pico requires PHP >= 5.3.6 (due to `erusev/parsedown-extra`)
* [Changed] Pico now implicitly uses a existing `content` directory without
the need to configure this in the `config/config.php` explicitly
* [Changed] Composer: Require a v0.7 release of `erusev/parsedown-extra`
* [Changed] #93, #158: Pico doesn't parse all content files anymore; moved to
`PicoParsePagesContent` plugin, but still impacts performance;
Note: This means `$page['content']` isn't available anymore, but
usually the new `$page['raw_content']` is suitable as replacement.
* [Changed] #116: Parse meta headers using the Symfony YAML component
* [Changed] #244: Replace opendir() with scandir()
* [Changed] #246: Move `config.php` to `config/` directory
* [Changed] #253: Assume HTTPS if page is requested through port 443
* [Changed] A vast number of small improvements and changes...
* [Fixed] Sorting by date now uses timestamps and works as expected
* [Fixed] Fixing `$currentPage`, `$nextPage` and `$previousPage`
* [Fixed] #99: Support content filenames with spaces
* [Fixed] #140, #241: Use file paths as page identifiers rather than titles
* [Fixed] #248: Always set a timezone; adding `$config['timezone']` option
* [Fixed] A vast number of small bugs...
* [Removed] Removing the default Twig cache dir
* [Removed] Removing various empty `index.html` files
* [Removed] Moving Pico's excerpt feature to `PicoExcerpt` plugin
```
|
Here we go 😃 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 http://picocms.org/ requires a forced Refresh to work (Strg + F5). |
|
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. |
|
Added |
theshka
changed the title
I think the link to cookbook would be good in the |
|
I suggest to fit a |
|
Considering there have been numerous large changes between 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 |
|
Hmm... Makes it harder for |
|
Alternatively, can we hide/prefix the files |
|
Yeah, renaming |
|
Made the changes in #295, whenever you get a free minute, just make sure I didn't miss any :) |
|
Sorry @PhrozenByte, just to clarify... should we clear up the 4 remaining PR's and 4 "To-Do" items in this thread before tagging |
|
#273 looks good, I like the improved error handling and the update to the inline docs is great 👍 ... I also renamed the milestone and moved the discussed issues to the next version. |
|
Nice! 👍 Auto docs is awesome 😍 Also, #289 🙏 |
|
😃 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. |
|
Awesome work 👍 It only gets better and better 😃 |
|
@PhrozenByte deserves I'm behind the Twitter account thus far, more of a manual-bot at the moment @Lomanic lol |
|
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 😃 Pico got an community project as its best 😃 |
|
I would like to suggest the release of the final As elucidated in #297 (comment), I'm planning to release Pico 1.1 pretty soon (by way of comparison: #252 is 4 months old, What do you think? (especially, but not exclusively, @theshka) |
|
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. 😃 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. 🎉 👍 |
|
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! 😃 |
|
I've modified the due date on Version 1.0.0 Milestone, Merry Ho-Ho 🎅 👍 |
|
Done 💝 😃 I would like to thank all of you guys who made this possible, either by code and documentation contributions, general support, reporting issues, giving ideas or by participating in discussions, helping us to find the best solution. Pico and the community we built together are awesome, thank you! Merry Christmas 🎅 and a Happy New Year 2016 🎆 |
The phpDocumentor folder of the
gh-pagesbranch (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.0release:CONTRIBUTING.md, added in bef1502upgrade.md, added in Restructured upgrade.md #276README.mdfor thegh-pagesbranch, added in 66bcb18Pico 0.X Pluginssection from website with the final release of Pico 1.0.0Deferred:
New default theme using Bootstrap 3 or (provided it has been released already) Bootstrap 4Website: Overhaul_development/collection resp.development.mdWebsite: Improve_cookbook/collection resp.cookbook.htmlDecide where to put links to it (inline user docs? website user docs? website dev docs?) and actually create the linksThe text was updated successfully, but these errors were encountered: