Page MenuHomePhorge

Develop a Phorge Release Process
Open, Unbreak Now!Public

Description

Following how it has been historically :

master contains bleeding edge
stable contains "released" code

Revisions are landed onto master
Code from master is merged into stable at some interval and according to some process

We need to define this process

  • What are the conditions for landing changes upstream
  • Who is in charge of it
  • How is it documented
  • How are release notes created
  • Where are these release notes stored?

We can sort of attempt to just recreate the Phabricator process, although this would also be an opportunity to revise if desired

References

Event Timeline

I created Release Process in our internals wiki to start the documentation on what the release process would look like, based on some of those commented. As we flesh out the plan I’d like to update that.

TBH, I don't think we need to revise it, especially not at this time. It's been working. If we find there are problems with it later down the road, we can revise.

I created a change log just so we could begin documenting changes as they happen.

I would love to help with release management if there are volunteers needed.

In T15014#446, @speck wrote:

I created Release Process in our internals wiki to start the documentation on what the release process would look like, based on some of those commented. As we flesh out the plan I’d like to update that.

Can you give me access to see that document?

fwiw the old upstream workflow has been very easy to follow as a downstream fork maintainer so I like keeping it mostly unchanged.

In T15014#446, @speck wrote:

I created Release Process in our internals wiki to start the documentation on what the release process would look like, based on some of those commented. As we flesh out the plan I’d like to update that.

Can you give me access to see that document?

In T15014#562, @avivey wrote:

Can I please have access to Release Process ?

Done, you've both been added to Security Viewers

Thanks :)

I think that for the time-being, we should just continue the stable/master approach, because we have a lot of other things to do.
We can always open this later if we feel a need.

speck triaged this task as Unbreak Now! priority.Jun 24 2021, 01:07

I'm redirecting the discussion from D25011 to this task

A few things on here.

I have a lot of concerns about what is happening with these Harbormaster updates. I believe them to be good strategy, and should be welcomed, however..............

  1. We should stave off any updates to the core until the Phorge re-brand is complete

Slowing things down is rarely a good idea ever - at least for the reasons external to the patch in question, rejecting a patches because it's not good if obviously just fine. I reject that point outright.

If the rebranding effort isn't moving fast enough that it is slowing down other stuff, thinking about how to speed it up should be the reflex, not slowing other stuff down.

In D25011#376, @jupe wrote:

I have the feeling that the issue at hands is a different perception of priorities. I agree with you on the fact that we should be goal oriented: right now different people might have different goals in mind.

Yes, that's well and good, but, there is no reason to slow stuff down because you think something else is higher pri. Just go work on the higher pri stuff. It makes no sense to delay what you don't think is the highest pri, unless you wish thing to fit into a pre-established process - we do X because it is the highest pri, then we do Y. In such a case, the process would not be servicing the project, because delaying Y in no way speeds up the realization of X, it simply delays Y.

Can you imagine Google saying "youtube is our highest priority this quarter, therefore, we'll stop all work on search". Would that make sense? And if not, why are we effectively doing it?

The concerns aren't about the work being done as much as they are about the changes are being landed upstream. Phorge needs to become a proper, legal fork of Phabricator before other changes start landing upstream, I believe requiring:

However you are right that these tasks not being completed should not prevent people from planning out, submitting diffs, and having discussions about the changes. In the meantime we should hold off on landing changes in the upstream repository which aren't related to the above tasks, until those are completed.

I think this is not being communicated well which is likely causing some misalignment right now. @avivey has started triaging some of these tasks to help reflect what needs done now. I will also spend some time to flesh out a task tree based on what's listed above, though I'm not sure how to better indicate that those things must be completed prior to other changes landing upstream.


Here are my views on some of the other discussion points that came up:

  1. This revision is not linked to any task, but should be attached to T15018

Feel free to link it. But there too, this doesn't seem like a good idea to me to put administrative barriers in place.

Using tasks has benefits and I personally would consider a diff/revision without an associated task to be the exception rather than standard practice. Here are some of the benefits I would like to see from using tasks:

  1. They allow for further design and discussion to be fleshed out before time and effort are spent on development and testing
  2. Because of #1 they should then encapsulate some of the design and reasoning
  3. They aid with planning (e.g. project workboards)
  4. They are more easily discoverable by newcomers, especially helping to read-up on the design/expected use
  5. It is not uncommon for some development approaches to be started and then abandoned for a better approach. Having disparate diffs with parts of conversations can be pieced together but it doesn't give a cohesive view of what the work is for.
  1. There is no unit-test coverage

I don't see how this can be unit tested, because it is reaching to CircleCI. The original code isn't unit tested for that reason, and well, let's not be more royalist than the king. However, it'd be very disirable if we could try it on some project that uses CircleCI to confirm it isn't broken.

Like most things testing/coverage is a bit of an art or balance, though I don't believe we should be landing changes upstream which don't have any test coverage whether it's unit testing, manual testing, or ideally both. The big hesitancy with the current changes to the CircleCI integration is that we don't yet have someone from the community who is able to test these changes to verify things still work.

Anyways, why am I bringing this up? Because I'm seeing something worrying. While some of the concerns about that patch are actually about that patch - like we should probably test this better before it is merged - most actually are concerns about process. We need to do X before Y, link A to B, etc... I would urge everyone to fall for this trap. We need to keep in mind that we have zero users at the moment, and so we have very little need for the stability provided by a process oriented culture. We, however, will slow down our ability to have something worthy to put out there, possibly to the point were we never do.

I would instead encourage people to be more action and goal oriented. That means, if a task need to be attached, then just attach it. If it seems preferable to finish another project before the one in question moves on, wonder how this other project can be made to move faster. If you think the testing is not appropriate (which is completely fair, BTW) then please help finding some project using CircleCI that can be used for testing purposes.

We are setting the culture of that thing, let's ensure it doesn't turn into the DMV of software. There is enough of this out there.

I think I understand your concern about becoming too process-oriented. Right now there's a lot of excitement and motivation to build out Phorge and I also want to key-in on that to let community members build out ideas and make Phorge a great product. However I also feel really strongly that maintaining quality in Phorge be a continuing strength of the project. EvanP/Phacility provided this with Phabricator which I believe to be one of the reasons it has a dedicated community. Once in 6 years of using Phabricator we had only one issue arise from upgrading (not counting arcanist~) and it was a conflict between new updates and environment configuration. I would like to find a process that balances the process/quality in a way that still keeps people motivated but also provides end-users the assurances that the product isn't going to break or do unexpected things. Maybe this is doable by maintaining a third branch, which after testing can be merged into master and then stable? I want to explore these possibilities as part of this task. I would not want to push up untested changes, have people switch to Phorge, then have their processes broken. That breaks trust with the user base which is arguably more damaging than building/maintaining motivation.

I second everything @speck says here.

@deadalnix I hope you don't feel like you are being piled up on here! - That is not the objective, because in general, I feel that the work you are doing on Harbormaster is very valuable to the future of Phorge.

And @deadalnix I do agree with some of the organizational / goal stuff you are talking about, and I think once we get some of this early stuff worked out, we will be able to develop a path forward that meets alot of your objectives.

And further to that, don't let this prevent you from building out your proposed changes. These can be created and attached to appropriate tasks so they can be discussed and reviewed.

But keep in mind, one of the Goals of this project is stability and security. And especially with something like Harbormaster, we have to take time to review and test these code changes because we do not want to introduce any vulnerabilities. The tiniest little things sometimes lead to the biggest security issues with projects like this.

And finally, because of the community nature of this open source project, sometimes, we will get into the minutia of some proposed change. This is why we have to complete all of the startup organizational stuff T15023, so we have a process to get out of the muck when we get trapped in it.

In T15014#622, @speck wrote:

I'm redirecting the discussion from D25011 to this task

Fantastic!

Using tasks has benefits and I personally would consider a diff/revision without an associated task to be the exception rather than standard practice. Here are some of the benefits I would like to see from using tasks:

  1. They allow for further design and discussion to be fleshed out before time and effort are spent on development and testing
  2. Because of #1 they should then encapsulate some of the design and reasoning
  3. They aid with planning (e.g. project workboards)
  4. They are more easily discoverable by newcomers, especially helping to read-up on the design/expected use
  5. It is not uncommon for some development approaches to be started and then abandoned for a better approach. Having disparate diffs with parts of conversations can be pieced together but it doesn't give a cohesive view of what the work is for.

Everything you said is true, within reason, but let me take a step back.

Now, let's ask an important question: when does this helps, and when does this hurts to require a task to be linked to a diff? It is clear that it is not always useful, for instance, if one is to fix a typo in a comment, requiring that person to open a task, then open a diff linked to the task, than mark the task as resolves once the diff is landed would actually be harmful. The end result would be less typo fixed, due to the overhead, and therefore lower quality software. So this is an important question. The answer is simple: does it help things move faster.

Specifically about D25011 , it fits into a larger whole and indeed benefits from having a task. In fact, it has one now. But is it true for most diffs? I honestly think not. Most changes are self contained. Fixing a typo, or a simple bug do not and should not require such a thing, because that would simply slow down the rate at which bugs are fixed.

There is a sense of satisfaction that comes from creating a task, then doing it and then marking it as done. I know people who purposefully add stuff to their todo list before doing them so they can mark it as done. All good. But let's not confuse motion for progress. One can spend an infinite amount of time keep track of all the work that is being done, needs to be done and so on, and at the end of the day, no work gets done. Doing so is not useless, but in excess, it is harmful. It is useful to the extent it helps the work to be done faster.

And here, we have a problem. The rebranding is moving slowly. It's okay, it's a big task and it involve 3rd parties. I'm not blaming anyone here, and certainly not you @speck as you are the one who did the most work on that front afaict. But nevertheless, it is becoming clear that this is not going to get sorted out by tomorow. So what do we do? Do we stop everything? Well, if we use our yardstick to decide if it is a useful measure, what do we conclude? Is it helping shipping faster? No, clearly it does the opposite. This is an harmful process.

Incidentally, these concern are a big part of why phabricator was created in the first place. The dogma that existed at the time about how to build software didn't make sense to Facebook, because it was not helping moving forward. The fact that isn't widely understood makes me worried about the future of phorge if I'm being frank. To be fair, it is not easy nor it is obvious, as when I joined Facebook myself, I was shocked to see how thing were done there and really expected everything to turn bad in no time. Surely, they couldn't go against almost every single established good practice in most companies and execept everything to go well? And yet, I chose to have a leap of faith, because, obviously, Facebook was shipping stuff quite quickly, it wasn't always broken, and therefore there must have been something that I was missing.

However I also feel really strongly that maintaining quality in Phorge be a continuing strength of the project. EvanP/Phacility provided this with Phabricator which I believe to be one of the reasons it has a dedicated community.

I have to take exception with this. Yes, we must uphold standard of high quality, but this is EXACTLY what is being achieved in the patch that started this discussion. Better separation of concerns, better encapsulation and better extensibility are being provided. In fact, the need to move in that direction is mentioned by the man himself in this diff . So yes, this statement is true, but it is completely irrelevant to the situation at hand. In fact, Evan knows that this thing is built wrong, because

Once in 6 years of using Phabricator we had only one issue arise from upgrading (not counting arcanist~) and it was a conflict between new updates and environment configuration. I would like to find a process that balances the process/quality in a way that still keeps people motivated but also provides end-users the assurances that the product isn't going to break or do unexpected things. Maybe this is doable by maintaining a third branch, which after testing can be merged into master and then stable?

This is my experience too. This has been discussed extensively on zulip, and the conclusion was that there is a need to make things extensible so that we don't need to mess with the core and can allow things to be built independently, even maybe creating a store of sort. Once again, the change goes in that direction. We can make this extensible now, and ensure we don't need to mess with it in way that is likely to break later, upholding that promise to users, or we can wait and do it later, but the cost of doing so will never be as cheap as it is now that we don't have a release out.

Let restate: moving faster means less bugs and breakage - granted things move in the right direction - because the design can evolve in the right direction faster, and more bugs can be fixed. This runs counter to what intuition would tell us. This runs counter to what most "good practices" would tell you. And yet it is true.

I do not think we have a specific need for a extra branch other than master and stable. I do not think we should merge the patch before it has gone through a round trip with CircleCI. I would like have help setting this up so that we can move on.

I want to explore these possibilities as part of this task. I would not want to push up untested changes, have people switch to Phorge, then have their processes broken. That breaks trust with the user base which is arguably more damaging than building/maintaining motivation.

I do not want to push untested changes either. This is why I requested help in the patch to be able to do a real life trial of CircleCI so that we can check this all works. I have to note that I am not getting any help there, but instead an endless stream of nebulous concern about quality, breakage, now security.

I'll be blunt once more. These concerns are a very good way to sound smart saying things everybody know. Does it really come at a surprise that we must avoid breaking stuff for users? Or that we need to pay attention to security? Really? Next in line is "Yes but does it scales?"

These do not help anything get done. They do not improve anything, they do not fix any bug, in fact, they do not even improve things on the subject matter they pretend to address because they contains zero useful insight. They are just virtue signaling. "Look at me, I care about security!".

Now, can we get a setup with CircleCI going so that we can test things?

Now, can we get a setup with CircleCI going so that we can test things?

Everybody else is busy with the rebrand/startup process. You should be able to create a free account and test from your own environment - I think that's how Evan developed it originally.


For everything else - we need to have some processes in place. About what gets accepted and what doesn't. We're still working on it (and I'm not sure this particular discussion is moving it forward, except by maybe showing urgency).

I feel strongly that almost all bugs and features should have tasks before diffs, because describing the problem should always precede the solution.

Also, software quality at Facebook is kinda crap. The overall product works very well, but it is full of bugs. Facebook can get away with it by not being a software company - it's a service provider with code.

Also keep in mind that your changes will not ship anywhere until the bootstrap process is done, so you're not actually moving faster.

Note - nothing I say is about this particular diff, because I didn't look at it. I don't have much time, and I like to dedicate all of it to the high pri stuff. I'm sure others have ignored it for the same reason.

In T15014#671, @avivey wrote:

Now, can we get a setup with CircleCI going so that we can test things?

Everybody else is busy with the rebrand/startup process. You should be able to create a free account and test from your own environment - I think that's how Evan developed it originally.

This is fine. I'll do so when I have bandwidth for that, if someone else has bandwidth for that that'd be fantastic, what's not fantastic is what's happening now. I chose to focus on something else because it doesn't look like there is much to be added to what's being done on this front, it's not a manpower issue, and when it becomes one, then you can count on me.

For everything else - we need to have some processes in place. About what gets accepted and what doesn't. We're still working on it (and I'm not sure this particular discussion is moving it forward, except by maybe showing urgency).

As far as I can tell, the best is to have a group of owner, with consistent expectations, and make sure the process is that someone in this group accepts the patch.

In practice that is enough, and provide more flexibility as we figure things out. It also remarkably difficult to come up with a consistent set of measure that work. In practice, you are often better off tinkering with linters and alike to get people to do the right thing, rather than writing huge docs.

I feel strongly that almost all bugs and features should have tasks before diffs, because describing the problem should always precede the solution.

It's always a tradeof. Frederic Bastiat phrased it nicely with the seen and the unseen. What you see is all the thing being done tracked nicely and all. What you don't see is the trivial stuff that isn't taken care of that would have been if people could just send a patch. And if more needs to be discussed, then creating a task is still possible.

If you do not like Facebook, then LLVM is a good example. I hope you'll agree that it both have a high bar in term of quality and avoiding bugs in there is really important - if we are honest, more important than it'll probably ever be for us. Their process is rather straightforward too and they move quickly too. Just send patch, and get a committer to accept it. In practice, the person familiar with the clang frontend isn't going to accept a change in the X86 codegen and vice versa. If the change is larger, or involve some cross cutting changes, then discussing it with affected parties and coming up with a battle plan is necessary, obviously. I think we should just do the same.

A few final thoughts here as well

  • Phorge was branched from Phabricator and T15000 was created 14 days ago - This is barely enough time to figure out some basic setup and infrastucture stuff let alone develop the strategy for an entirely new open source software project. Even further than this, this is forked from an already existing and stable project It is completely prudent to keep the brakes on for a sec while this stuff gets figured out
  • Tasks before diffs...always... The task describes the issue and one or more revisions resolves this issue. The lift requred to create a task is so minimal that I am surprised that this is a point of contention
  1. Create a task
  2. Create a branch in form of Txxx-BranchName
    • Your revision will be automatically linked to the task - no manual work
  3. Write your revision and comment Fixes Txxx in the summary
  4. When you land your revision - Task is automatically closed

In fact, once arc work is completed for task handling, you can do arc work Txxx from the cli and it automatically creates the branch - simple and easy

What would be immensely worse, is a process that says "If the developer does not feel a task is required, then don't make one" - This is chaos.. If you have 10 developers, you will have 10 different versions of "when is a task required?" - This is solved simply by saying : "Make a task describing the issue, attach your revision to it"

, if one is to fix a typo in a comment, requiring that person to open a task, then open a diff linked to the task, than mark the task as resolves once the diff is landed would actually be harmful.

How? - Again, the work required to create a task is so minimal - We have literally spent more time discussing "should we create a task" then the time it takes to create 100 tasks

A few final thoughts here as well

  • Phorge was branched from Phabricator and T15000 was created 14 days ago - This is barely enough time to figure out some basic setup and infrastucture stuff let alone develop the strategy for an entirely new open source software project. Even further than this, this is forked from an already existing and stable project It is completely prudent to keep the brakes on for a sec while this stuff gets figured out
  • Tasks before diffs...always... The task describes the issue and one or more revisions resolves this issue. The lift requred to create a task is so minimal that I am surprised that this is a point of contention
  1. Create a task
  2. Create a branch in form of Txxx-BranchName
    • Your revision will be automatically linked to the task - no manual work
  3. Write your revision and comment Fixes Txxx in the summary
  4. When you land your revision - Task is automatically closed

In fact, once arc work is completed for task handling, you can do arc work Txxx from the cli and it automatically creates the branch - simple and easy

What would be immensely worse, is a process that says "If the developer does not feel a task is required, then don't make one" - This is chaos.. If you have 10 developers, you will have 10 different versions of "when is a task required?" - This is solved simply by saying : "Make a task describing the issue, attach your revision to it"

, if one is to fix a typo in a comment, requiring that person to open a task, then open a diff linked to the task, than mark the task as resolves once the diff is landed would actually be harmful.

How? - Again, the work required to create a task is so minimal - We have literally spent more time discussing "should we create a task" then the time it takes to create 100 tasks

Just a further note here: The documentation requires a task be created before work is performed. If that is not the case, our documentation needs to be updated as well... (ref)

I think it makes sense to find some balance based off the impact of a change. If someone is submitting some code documentation changes or typos then I would personally be fine with not requiring a task as long as the diff itself can encompass the details and lints/unit-tests to account for syntax errors. What I'm worried about are larger changes which don't have tasks, as that means someone is putting time into larger changes without seeking input/discussion from others about how to approach the problem. Additionally it may also be possible that someone else is working on a similar change resulting in either duplicated or conflicting efforts.

(I'm 100% with @speck on requiring tasks)

Since there is no objections to the release process here (only discussion around the use of tasks), I'd like to propose that we begin promoting to stable shortly. I'd say let's cut the Monday following the week of the release, so the next release will happen July 5 for version 2021.26 (2021 Week 26).

I'd like to volunteer to help maintain the releases if that's OK. It's something I absolutely love (tracking changes and maintaining documentation) and I think it'll be a great way for me to support this project.

I'd like to volunteer to help maintain the releases if that's OK. It's something I absolutely love (tracking changes and maintaining documentation) and I think it'll be a great way for me to support this project.

That sounds great to me! I'm a fan of having someone be the primary release engineer/manager and your volunteering would be very valuable for the project.

I'd say let's cut the Monday following the week of the release, so the next release will happen July 5 for version 2021.26 (2021 Week 26).

I think going through this process will be good to figure out the details of what all is needed, but I'm unsure about cutting a release until the project has been rebranded. I don't like holding up the process but there might be some legal hiccups due to "Phabricator" and "Phacility" being trademarked. What are others' thoughts?

In T15014#769, @speck wrote:

I'd like to volunteer to help maintain the releases if that's OK. It's something I absolutely love (tracking changes and maintaining documentation) and I think it'll be a great way for me to support this project.

That sounds great to me! I'm a fan of having someone be the primary release engineer/manager and your volunteering would be very valuable for the project.

I agree. And I would love to take that on!

I'd say let's cut the Monday following the week of the release, so the next release will happen July 5 for version 2021.26 (2021 Week 26).

I think going through this process will be good to figure out the details of what all is needed, but I'm unsure about cutting a release until the project has been rebranded. I don't like holding up the process but there might be some legal hiccups due to "Phabricator" and "Phacility" being trademarked. What are others' thoughts?

Fair enough. I'm also concerned over the actual process, specifically around setting up the permissions around O1.

How about this? I'll take care of cutting a release the Monday after T15006 is closed. I think that would be a good compromise, especially around the legal stuff. Until then, I'd love to maintain the change log like I have been (so we don't have to scramble and build one right after a release).

That sounds good to me. I'm hoping to get back to a new approach for T15006 later this week, in cooperation with upstream

I was discussing with @deadalnix a bit and I think it would make sense to retain branches in our fork that represent the master and stable branches from upstream, but not be the primary branches we commit/land phorge into. That would allow us to keep synced with upstream's changes and regularly merge those in. I think operating in this way would also let us be a little more flexible with allowing other changes to be worked on and landed in the phorge branches without being blocked by the rebrand changes. Then at some point in the future the rebrand changes would come in from the upstream branch, merge in, and we could make an official Phorge release.

That would leave us with these branches

  • master - Our primary landing branch for phorge changes
  • stable - Our primary release branch for phorge changes
  • phab-master - Directly pulled from upstream master
  • phab-stable - Directly pulled from upstream stable

If we do this, then does that mean we merge phab-stable -> stable and phab-master in to master? That might get tricky since upstream merges master into stable. Maybe we shouldn't bother with upstream's master branch and only do this for stable?

nit-pick: maybe name them phabricator/master and phabricator/stable.

But why would we need to explicitly keep them? They already exist upstream...

Also, I'd go with only master rather then only stable - it actually has less noise (all the merge commits).

nit-pick: maybe name them phabricator/master and phabricator/stable.

I'm fine with whatever naming

But why would we need to explicitly keep them? They already exist upstream...

My suspicion, though I hadn't thought through it much, is that it might be useful during migration periods where someone has the repository checked out and there's are clear linear branches of the phabricator development vs. phorge development.

Also, I'd go with only master rather then only stable - it actually has less noise (all the merge commits).

Ah that makes sense

FWIW I think the master / stable split happened upstream due to some planned deep rewrites. For our process I'd rather go masteronly and not have a separately stable or release branch.

But why would we need to explicitly keep them? They already exist upstream...

My suspicion, though I hadn't thought through it much, is that it might be useful during migration periods where someone has the repository checked out and there's are clear linear branches of the phabricator development vs. phorge development.

Having an upstream remote called phabricator in your local Phorge repo should be enough to get the phabricator/master and phabricator/stable branches, so there might not be any reason to push them to the hosted Phorge repo. Everyone who wants to interact with the upstream branches can opt in by adding a remote.

Once phabricator/master and master diverge so much that it doesn't make sense to merge one into the other anymore, the next strategy might be to cherry-pick individual commits. At that point, to ensure that we have a complete record of the Phabricator history in case the upstream disappears, we could host a mirror of the Phabricator repo or explicitly introduce the upstream branches into the Phorge repo.

If it's not worthwhile then let's not do it

In T15014#929, @avivey wrote:

nit-pick: maybe name them phabricator/master and phabricator/stable

This seems like a common, recognizable naming pattern, safe bet

There already are a bunch of worthwhile changes in Phabricator we should pick up; @Matthew - want to load them to check out the procedure? I can do that otherwise.

Handling of merging upstream changes will probably lead to some challenging merges done by people who did not author the original changes in Phorge. I don't know what the best way is to work around this. Maybe if we regularly (daily?) pull in changes from upstream, merge into our own master branch which everyone lands onto that should mostly catch merge issues?

I can help out with upstream merges. I've been doing it on a regular basis for Wikimedia for a long time now. It's rarely been a problem but I'm been careful to make sure that Wikimedia's fork doesn't drift too far away from upstream.